摘要：从项目整体架构出发，拆解一个 HarmonyOS 化学学习应用如何组织入口、页面、模型、工具层和上架能力。

目录

• 1. 项目背景与目标
• 2. 需求拆解与工程边界
• 3. 架构设计与数据流
• 4. 核心代码实现
• 5. 技术细节补充
• 6. 踩坑记录与审核视角
• 7. 验证方式与可复用清单
• 8. 总结

1. 项目背景与目标

从工程实践看，教育类 HarmonyOS 应用不能只做页面堆叠，而要把“入口、状态、数据、系统能力、审核材料”放在同一条链路里设计。入口决定用户能不能快速到达核心能力，状态决定页面切换和返回时是否可靠，数据决定学习结果能不能沉淀，系统能力决定是否真正像一个端侧应用，审核材料则决定更新包能不能顺利上架。化学实验室这个项目的价值也在这里：它既有实验模拟这种可视化交互，也有阅读、朗读、每日一题、错题本、服务卡片、保存分享和更新包这些发布侧能力。

写这组文章时我采用的是“项目复盘 + 可复用方案”的结构。每篇文章都先说明业务问题，再明确工程边界，然后给出模块职责、数据流、关键代码、踩坑点和验证方式。这样写的好处是读者不只是看到某个 API 的用法，而是能看到为什么要这样拆、哪些地方容易被审核或真机测试卡住、如何把一个看起来简单的功能做成稳定可交付的模块。

本篇聚焦的是 架构设计。在化学实验室项目中，这个模块不是孤立功能，而是连接学习路径、用户反馈和上架稳定性的关键节点。用户侧看到的是一个按钮、一个页面或一张卡片，工程侧需要保证路由、状态、数据、异常、视觉和审核材料都能对上。尤其是 HarmonyOS/ArkTS 项目，如果页面里混入太多平台能力调用，后期一旦遇到真机差异、生命周期变化或审核反馈，就很难快速定位。

2. 需求拆解与工程边界

这个模块的需求可以拆成三层：第一层是用户可见能力，也就是用户点击后到底能完成什么；第二层是状态和数据能力，也就是这个动作能不能被保存、恢复、复盘；第三层是发布和审核能力，也就是这个功能是否与权限、隐私、截图、更新说明一致。

具体到本文主题，我会优先确认这些边界：页面是否只做展示和事件分发；服务是否能独立处理数据；失败状态是否能被用户理解；离开页面、返回页面、重新打开应用后行为是否稳定；最终构建出的 release 包是否可以支撑 AppGallery 审核路径。

3. 架构设计与数据流

从分层上看，本模块可以拆成下面几类职责：

写在最后：卑微作者在线求一个下载和反馈

这篇是这个系列的第一篇，能写到这里真的挺不容易的。为了把这个 HarmonyOS 化学实验室项目从功能、打包、卡片、上架素材到踩坑复盘讲清楚，我基本是按真实项目路径一段段拆出来的，不是随便拼一篇水文。

如果你觉得这篇文章对你有一点点帮助，麻烦顺手帮我点个赞、收藏一下，评论区留一句你的看法也行。更重要的是，欢迎下载体验一下这个“化学实验室”应用，帮我点点实验模拟、每日一题、错题本、化学阅读朗读和服务卡片这些功能。要是发现哪里不好用、哪里还能优化，也请直接在评论区告诉我。

独立做应用和写技术文章都挺苦的，很多时候不是缺想法，而是缺真实用户的一句反馈。你的一个下载、一次体验、一条评论，可能就能帮我把下一个版本做得更稳一点。先在这里认真谢谢你。

如果你要把这套方案复用到自己的项目里，可以先不追求功能数量，而是优先保证三个闭环：入口闭环、数据闭环、发布闭环。入口闭环保证用户能找到功能；数据闭环保证用户做过的事能留下结果；发布闭环保证你提交给平台的包、截图、说明和隐私材料是一致的。

8. 总结

第一篇：HarmonyOS 化学实验室从 0 到 1：一个离线教育 App 的完整架构设计 这一篇的核心结论是：不要把功能做成孤立页面，而要把它放进完整产品链路里看。一个按钮背后应该有状态，一个结果背后应该有模型，一个上架说明背后应该有真实功能，一个宣传图背后应该有可验证的页面。这样写出来的代码更稳定，写出来的文章也更有技术含量。

• **产品入口层**：首页、实验室、学习中心、我的四个一级入口，负责承载核心用户路径。
• **业务页面层**：实验模拟、阅读、每日一题、错题本、记录页面按场景独立演进。
• **能力封装层**：DataStore、ShareUtils、ReadingSpeechService 封装平台能力，降低页面耦合。
• **发布扩展层**：服务卡片、签名包、AppGallery 素材和更新说明共同组成发布能力。

• 数据流建议遵循一个简单规则：用户操作进入页面，页面组装最小参数，业务服务完成计算或持久化，服务返回明确结果，页面根据结果更新状态。不要让页面直接拼接复杂对象，也不要让工具类反过来控制 UI。这样做的收益是调试路径清晰：如果 UI 没反应，看页面事件；如果数据没保存，看服务返回；如果分享不对，看 payload；如果审核不过，看核心流程证据。

  4. 核心代码实现

  下面这段代码展示了本文主题里最核心的结构。真实项目可以继续拆分到 model、utils、views 或 formability 目录中，但思想是一致的：先定义模型，再定义动作，最后由页面触发。

• export interface LearningEntry {   id: string   title: string   route: string   icon: Resource } const homeEntries: LearningEntry[] = [   { id: 'lab', title: '开始实验', route: 'pages/LabPage', icon: $r('app.media.ic_lab') },   { id: 'reading', title: '化学阅读', route: 'pages/ReadingListPage', icon: $r('app.media.ic_reading') },   { id: 'quiz', title: '每日一题', route: 'pages/DailyQuizPage', icon: $r('app.media.ic_quiz') }, ]

  再补一个通用的页面状态封装。HarmonyOS 页面经常要面对加载、空数据、错误、保存中、分享中等状态，如果每个页面都临时写布尔值，后期会非常乱。可以把状态抽象成统一结构，再按模块扩展：

  interface PageState<T> {   loading: boolean   error: string   data?: T } async function runSafely<T>(task: () => Promise<T>): Promise<PageState<T>> {   try {     const data = await task()     return { loading: false, error: '', data }   } catch (err) {     return { loading: false, error: `${err}` }   } }

  这个封装不复杂，但能明显减少页面里的临时判断。比如保存实验结果时，按钮可以根据 saving 禁用；加载阅读文章时，可以根据 loading 展示骨架或空状态；错题本为空时，可以根据 data.length 展示复习引导。

  5. 技术细节补充

  在架构设计这一篇里，最重要的技术点是“页面不直接拥有所有能力”。例如首页只负责展示入口和触发路由，实验结果保存交给结果存储服务，阅读朗读交给语音服务，服务卡片交给 FormExtensionAbility。这样做虽然一开始会多几个文件，但后期排查问题会快很多。比如审核反馈“实验结果无法保存和分享”时，我们可以直接定位到结果模型、存储服务和分享服务，而不是在页面里翻大量 UI 代码。

  另一个关键点是数据边界。化学实验室属于离线教育应用，默认不应该依赖网络、账号、广告或云同步。文章里的目录设计也围绕这个前提展开：学习内容、题库、实验结果和错题记录都可以本地优先；需要展示给用户的结果必须结构化；需要跨页面读取的状态通过服务层提供，而不是把页面实例或 Context 当作全局变量到处传。

  还有一个容易被忽略的点：所有用户能看到的功能，都应该能在代码里找到对应的数据结构。比如“实验结果”不应该只是页面上的几行 Text，而应该是可保存、可分享的 ExperimentResultPayload；“每日一题”不应该只是按钮点击后变颜色，而应该有 Question、AnswerState 和 WrongQuestionItem；“服务卡片”不应该只是桌面装饰，而应该有清晰的卡片数据来源和跳转目标。

  6. 踩坑记录与审核视角

  从 AppGallery 审核角度看，最容易被打回的不是大而复杂的功能，而是用户一眼能测出来的核心异常。例如按钮点了没反应、结果无法保存、分享入口无效、退出页面后播放被打断、深色模式文字看不清、截图展示的功能和包里不一致。这些问题都属于体验和稳定性问题，严重时会落到审核指南 3.1 的范围。

  因此每次改完功能，我建议都写一条最小回归路径。本文主题的路径可以表示为：

• 打开首页
• 进入实验
• 生成结果
• 保存或分享
• 回到学习

• 这条路径必须在 release 或准 release 包里跑通，而不是只在 Previewer 或 debug 环境里看页面。尤其是签名、卡片、分享、朗读、安装更新这类能力，debug 表现和上架包表现可能不同。

  7. 验证方式与可复用清单

  发布前我会按下面清单逐项确认：

• 一级入口不超过用户理解负担，首页可以快速进入阅读和实验。
• 业务页面不直接操作底层持久化，统一走服务层。
• 页面返回、退出、重进后核心状态不能丢失。
• 离线教育应用不声明无关网络和敏感权限。
• 上架前保证安装、启动、核心流程、卸载全部可验证。

写在最后：作者在线求一个下载和反馈

这篇是这个系列的第一篇，能写到这里真的挺不容易的。为了把这个 HarmonyOS 化学实验室项目从功能、打包、卡片、上架素材到踩坑复盘讲清楚，我基本是按真实项目路径一段段拆出来的，不是随便拼一篇水文。

如果你觉得这篇文章对你有一点点帮助，麻烦顺手帮我点个赞、收藏一下，评论区留一句你的看法也行。更重要的是，欢迎下载体验一下这个“化学实验室”应用，帮我点点实验模拟、每日一题、错题本、化学阅读朗读和服务卡片这些功能。要是发现哪里不好用、哪里还能优化，也请直接在评论区告诉我。

独立做应用和写技术文章都挺苦的，很多时候不是缺想法，而是缺真实用户的一句反馈。你的一个下载、一次体验、一条评论，可能就能帮我把下一个版本做得更稳一点。先在这里认真谢谢你。