本文是“足球口袋教练 HarmonyOS 离线应用实战”系列第 1 篇。示例项目是一个 HarmonyOS / ArkTS / ArkUI 编写的离线足球训练助手，围绕真实页面、真实截图和可复现操作展开。

本篇要解决的问题

训练类 App 很容易被做成内容堆砌：有课程、有卡片、有按钮，但用户不知道今天练什么，开发者也不知道哪些数据应该留下来。足球口袋教练的第一篇从产品约束开始，明确它不是云端社区，而是一个打开即可训练的本地工具。

这篇文章的目标不是把所有代码逐行解释完，而是给出一个能被复用的工程切入点：先确定用户行为，再确定状态来源，最后确定页面如何反馈。对于训练类应用，这个顺序尤其重要，因为用户不会为了欣赏界面而打开 App，他打开它通常是为了开始一次明确的训练。

项目中的实现选择

本项目把训练课程、周计划、训练记录、成就、主题偏好与个人资料放在同一个本地闭环中。核心页面集中在 Index.ets，利于 MVP 快速验证；文章会把单文件方案的收益和风险都摊开，包括迭代速度、状态集中、后续拆分成本。

在当前版本里，很多能力被集中放进 Index.ets，这是一种适合 MVP 的取舍。它让需求验证、截图验收和 CSDN 复盘都更快，但也意味着当课程数、状态数、语音逻辑继续增长时，要逐步拆分出 service、repository 和 component 层。文章示例会保持这个边界感：先解释当前方案为什么能跑通，再说明下一阶段应该怎么演进。

关键代码片段：用模块目录定义产品信息架构

const TRAINING_MODULES: TrainingModule[] = [
  { id: 'skill', title: '技巧训练', shortName: '技巧', color: '#2E7D32' },
  { id: 'strength', title: '力量训练', shortName: '力量', color: '#4A90E2' },
  { id: 'tactic', title: '战术策略', shortName: '战术', color: '#7E57C2' }
];

这段代码对应的重点不是语法本身，而是它在业务链路里的位置。训练应用的代码可以按四类来读：

1. 静态目录：课程、模块、默认计划和徽章规则。
2. 用户状态：收藏、训练记录、计划完成情况、主题、画像。
3. 页面状态：当前 Tab、当前课程、搜索结果、训练计时和图解查看器。
4. 系统能力：TTS、AVSession、后台任务、资源引用和构建安装。

只要能把变量放回这四个桶里，后续排查问题会容易很多。比如收藏丢失通常看持久化，计时错乱通常看页面状态，训练统计不准则回到训练记录。

工程证据与可复现操作

这部分不列作者电脑上的文件目录，因为读者无法访问那些路径。更可复用的证据是页面截图、关键状态模型、核心代码片段和操作步骤。

• 先从首页确认“今日推荐训练、计划入口、训练统计、收藏入口”是否形成闭环。
• 再进入对应功能页，观察截图中的按钮、列表、状态文案是否与代码片段描述一致。
• 最后按“开始训练、完成记录、查看数据反馈”的顺序走一次主流程，确认状态能同步到计划、数据和成就模块。

可迁移到其他 HarmonyOS 项目的经验

第一，先把“静态内容”和“用户行为”分开。课程目录、默认计划、徽章定义和资源映射属于静态内容，可以随着版本发布；训练记录、收藏、主题、画像和计划完成状态属于用户行为，必须能持久化、能恢复、能被统计。很多页面问题不是 ArkUI 写法本身造成的，而是这两类数据混在一起后，页面无法判断到底应该读模板还是读用户状态。

第二，页面状态要有明确生命周期。比如当前选中课程、是否展示搜索结果、是否进入主动训练、是否打开图解查看器，这些都只是当前页面会话中的状态。它们不应该被保存成长期数据，也不应该影响下一次打开应用后的默认体验。训练记录和收藏可以留下，弹窗、缩放偏移、临时搜索词则应该在合适的返回或关闭动作里清理。

第三，技术文章要给读者留下验证路径。只写“实现了计划生成”说服力不够，最好同时给出关键代码片段、真实截图、操作路径和验证命令。这样读者可以判断这个功能是已经落地的能力，还是仍停留在方案设计。对于 CSDN 系列，工程证据越清楚，越容易被认为有原创性和实践价值。

第四，离线优先并不等于功能简陋。它更像是一种约束：不依赖账号、不依赖服务端、不上传训练隐私、不用网络失败阻断核心流程。在这个约束下，规则引擎、静态课程库、本地语音提示、本地报告和本地截图验收都可以形成完整体验。后续如果要接入云同步或 AI 能力，也应该先保证离线闭环不被破坏。

常见坑与规避方式

• 只在 UI 里写课程文案，导致搜索、计划、收藏、统计都拿不到结构化数据。
• 完成训练后只改按钮状态，没有生成 TrainingRecord，数据页和成就墙无法同步。
• 收藏保存整份课程对象，课程目录更新后收藏列表出现旧字段或旧文案。
• 主题切换只改页面背景，忽略文字、边框、卡片、按钮和空状态。
• 截图使用宣传图或旧图，和当前源码实现对不上，发布后读者无法复现。
• 在文章里粘贴本机签名配置、证书路径或密码字段，造成不必要的安全风险。

发布到 CSDN 前的高质量检查

• 标题保持统一格式：足球口袋教练 HarmonyOS 离线应用实战（01/20）：从产品定位到技术路线
• 摘要包含“问题、实现、验证”三要素，避免只写宣传语。
• 文章内至少保留一张真实 App 截图和一个代码片段。
• 不暴露本机签名密码、证书密码、API Key 或私有账号信息。
• 如果提到 HarmonyOS API 行为，优先补充官方文档链接，避免只引用二手博客。
• 如果截图更新，优先使用当前运行中的真实 App 截图，不使用商店宣传图冒充运行截图。

高质量补强：产品技术路线如何落到工程决策

为了让这篇文章不只停留在“项目介绍”，我把产品定位继续拆成工程决策表。读者真正关心的不是我做了多少页面，而是为什么这个足球训练助手要离线优先，为什么第一版可以接受单页面聚合，为什么暂时不接服务端、账号系统和远程内容。

决策点	当前选择	选择原因	后续演进
数据来源	静态课程目录 + 用户本地记录	训练内容稳定，隐私敏感，离线体验更可靠	抽出课程仓库，支持版本化内容包
状态管理	页面状态与持久化状态并存	MVP 阶段能快速验证训练闭环	状态增多后拆成训练、计划、记录、主题服务
交互入口	首页先给训练建议，再给统计反馈	用户打开 App 的第一目标是开始训练	增加最近未完成任务和上次训练恢复入口
技术边界	ArkTS + ArkUI + 本地资源	避免网络依赖，模拟器和真机都能跑通	数据层稳定后再考虑云同步和 AI 复盘

把产品路线画成链路，可以得到下面这条主路径：

用户打开应用
  -> 首页给出今日建议
  -> 进入课程详情查看重点和准备事项
  -> 开始训练并记录时长
  -> 写入训练记录和计划进度
  -> 数据页、成就墙、报告页同步反馈

这条链路的关键不是页面数量，而是每个页面都承担清晰职责。首页负责决策，详情页负责解释，训练页负责执行，数据页负责反馈，我的页面负责长期偏好和画像。只要这个闭环跑通，后续扩展课程数量、替换图解资源、接入 TTS 或增加报告维度，都不会破坏核心体验。

从高质量技术文的角度看，这里还需要明确取舍。单页面集中开发并不是最终架构，但它适合 MVP：调试路径短，状态关联直观，截图验收方便。等课程、图解、语音和报告能力稳定后，再拆分服务层和组件层，重构收益会比一开始就抽象更清晰。

可复用判断清单

1. 功能是否离线可完成：如果不能，需要说明网络失败时的降级方案。
2. 用户行为是否能留下记录：完成训练、收藏课程、切换主题都应有状态来源。
3. 页面反馈是否能闭环：用户完成动作后，数据页和成就页应能看到变化。
4. 后续拆分是否有边界：课程、记录、计划、主题、语音不应长期混在同一职责里。
5. 安全信息是否被隔离：签名配置、证书路径、账号信息不进入文章正文。

小结

离线足球训练助手的产品边界、技术选型与第一版交付标准 是这篇文章的主线。足球口袋教练这个项目的价值不在于一次性塞满所有功能，而在于把训练内容、计划、记录、反馈和本地能力串成一个可运行闭环。读者照着这个思路做自己的训练类或知识类 App，也能先跑出一个离线可用的 MVP，再逐步拆分和增强。

参考资料

• Huawei Developer ArkUI Application Framework
• Huawei Developer ArkUI State Management Overview
• Huawei Developer ArkTS Components Reference