足球口袋教练 HarmonyOS 离线应用实战（02/20）：训练课程内容模型设计
足球口袋教练 HarmonyOS 离线应用实战（02/20）：训练课程内容模型设计
本文是“足球口袋教练 HarmonyOS 离线应用实战”系列第 2 篇。示例项目是一个 HarmonyOS / ArkTS / ArkUI 编写的离线足球训练助手，核心文件为
entry/src/main/ets/pages/Index.ets，当前截图位于doc/csdn-series/screenshots/。
本篇要解决的问题
训练课程如果只写在 UI 文案里，后续搜索、收藏、计划生成、图解绑定都会反复造轮子。内容模型必须先回答三个问题：课程属于哪个模块、一次训练需要多久、用户完成后如何回写统计。
这篇文章的目标不是把所有代码逐行解释完，而是给出一个能被复用的工程切入点：先确定用户行为，再确定状态来源，最后确定页面如何反馈。对于训练类应用，这个顺序尤其重要，因为用户不会为了欣赏界面而打开 App，他打开它通常是为了开始一次明确的训练。
项目中的实现选择
项目使用 TrainingItem 描述课程，字段覆盖模块、标题、训练时长、难度、进度、重点和步骤。这个结构足够简单，适合本地静态目录；同时又保留了 itemId/moduleId，可被计划任务、训练记录、收藏列表和图解资源复用。
在当前版本里，很多能力被集中放进 Index.ets，这是一种适合 MVP 的取舍。它让需求验证、截图验收和 CSDN 复盘都更快，但也意味着当课程数、状态数、语音逻辑继续增长时，要逐步拆分出 service、repository 和 component 层。文章示例会保持这个边界感：先解释当前方案为什么能跑通，再说明下一阶段应该怎么演进。
关键代码片段：课程条目的最小可用字段
interface TrainingItem {
id: string;
moduleId: string;
title: string;
durationMinutes: number;
difficulty: string;
progress: number;
focus: string;
steps: string[];
}
这段代码对应的重点不是语法本身，而是它在业务链路里的位置。训练应用的代码可以按四类来读：
- 静态目录：课程、模块、默认计划和徽章规则。
- 用户状态：收藏、训练记录、计划完成情况、主题、画像。
- 页面状态：当前 Tab、当前课程、搜索结果、训练计时和图解查看器。
- 系统能力：TTS、AVSession、后台任务、资源引用和构建安装。
只要能把变量放回这四个桶里，后续排查问题会容易很多。比如收藏丢失通常看持久化，计时错乱通常看页面状态，训练统计不准则回到训练记录。
代码证据与可复现路径
- 主要源码：
entry/src/main/ets/pages/Index.ets - 当前截图：
doc/csdn-series/screenshots/18-all-courses.jpeg - 构建命令：
hvigorw.bat assembleHap --mode module -p product=default --no-daemon - 页面入口：
entry/src/main/resources/base/profile/main_pages.json - 资源目录：
entry/src/main/resources/base/media
抽查基础控球、传接球、高位压迫、动态热身等课程，确认每个课程都有步骤、时长、模块和图解入口，避免只有标题没有可训练内容。
本地验证时建议先跑静态检查，再看截图，再跑模拟器。截图能证明页面状态，源码能证明实现路径，构建命令能证明项目不是“只存在于文章里”。
可迁移到其他 HarmonyOS 项目的经验
第一，先把“静态内容”和“用户行为”分开。课程目录、默认计划、徽章定义和资源映射属于静态内容，可以随着版本发布；训练记录、收藏、主题、画像和计划完成状态属于用户行为，必须能持久化、能恢复、能被统计。很多页面问题不是 ArkUI 写法本身造成的，而是这两类数据混在一起后，页面无法判断到底应该读模板还是读用户状态。
第二，页面状态要有明确生命周期。比如当前选中课程、是否展示搜索结果、是否进入主动训练、是否打开图解查看器，这些都只是当前页面会话中的状态。它们不应该被保存成长期数据，也不应该影响下一次打开应用后的默认体验。训练记录和收藏可以留下，弹窗、缩放偏移、临时搜索词则应该在合适的返回或关闭动作里清理。
第三，技术文章要给读者留下验证路径。只写“实现了计划生成”说服力不够，最好同时给出源码位置、截图位置、操作路径和构建命令。这样读者可以判断这个功能是已经落地的能力，还是仍停留在方案设计。对于 CSDN 系列，工程证据越清楚，越容易被认为有原创性和实践价值。
第四，离线优先并不等于功能简陋。它更像是一种约束：不依赖账号、不依赖服务端、不上传训练隐私、不用网络失败阻断核心流程。在这个约束下，规则引擎、静态课程库、本地语音提示、本地报告和本地截图验收都可以形成完整体验。后续如果要接入云同步或 AI 能力，也应该先保证离线闭环不被破坏。
常见坑与规避方式
- 只在 UI 里写课程文案，导致搜索、计划、收藏、统计都拿不到结构化数据。
- 完成训练后只改按钮状态，没有生成 TrainingRecord，数据页和成就墙无法同步。
- 收藏保存整份课程对象，课程目录更新后收藏列表出现旧字段或旧文案。
- 主题切换只改页面背景，忽略文字、边框、卡片、按钮和空状态。
- 截图使用宣传图或旧图，和当前源码实现对不上，发布后读者无法复现。
- 在文章里粘贴本机签名配置、证书路径或密码字段，造成不必要的安全风险。
发布到 CSDN 前的高质量检查
- 标题保持统一格式：
足球口袋教练 HarmonyOS 离线应用实战（02/20）：训练课程内容模型设计 - 摘要包含“问题、实现、验证”三要素，避免只写宣传语。
- 文章内至少保留一张真实 App 截图和一个代码片段。
- 不暴露本机签名密码、证书密码、API Key 或私有账号信息。
- 如果提到 HarmonyOS API 行为，优先补充官方文档链接，避免只引用二手博客。
- 如果截图更新，优先替换
doc/csdn-series/screenshots/下的真实截图，不使用商店宣传图冒充运行截图。
小结
把足球技巧、体能、战术、恢复等训练内容组织成可扩展的 ArkTS 数据结构 是这篇文章的主线。足球口袋教练这个项目的价值不在于一次性塞满所有功能，而在于把训练内容、计划、记录、反馈和本地能力串成一个可运行闭环。读者照着这个思路做自己的训练类或知识类 App，也能先跑出一个离线可用的 MVP，再逐步拆分和增强。
参考资料
讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。
更多推荐
1
0- 0
已为社区贡献52条内容
所有评论(0)