本文是“足球口袋教练 HarmonyOS 离线应用实战”系列第 3 篇。示例项目是一个 HarmonyOS / ArkTS / ArkUI 编写的离线足球训练助手围绕真实页面、真实截图和可复现操作展开。本篇要解决的问题训练 App 的首页不能只展示欢迎语它要解决“我现在该点哪里”的问题。足球口袋教练把首页定义为训练决策面板先给出建议再展示进度最后把用户引向计划或课程。这篇文章的目标不是把所有代码逐行解释完而是给出一个能被复用的工程切入点先确定用户行为再确定状态来源最后确定页面如何反馈。对于训练类应用这个顺序尤其重要因为用户不会为了欣赏界面而打开 App他打开它通常是为了开始一次明确的训练。项目中的实现选择首页由 MainShell、TrainingHomePage、统计卡、推荐训练卡和底部导航组成。ArkUI 的 Column、Row、Scroll 足够承载这个层级但需要控制卡片密度、按钮层级和状态提示避免首屏被装饰信息挤满。在当前版本里很多能力被集中放进Index.ets这是一种适合 MVP 的取舍。它让需求验证、截图验收和 CSDN 复盘都更快但也意味着当课程数、状态数、语音逻辑继续增长时要逐步拆分出 service、repository 和 component 层。文章示例会保持这个边界感先解释当前方案为什么能跑通再说明下一阶段应该怎么演进。关键代码片段Shell 负责页面切换首页负责训练入口Builder MainShell() { Column() { Stack() { if (this.activeTab 0) { this.TrainingHomePage() } else if (this.activeTab 1) { this.PlanPage() } } this.BottomNav() } }这段代码对应的重点不是语法本身而是它在业务链路里的位置。训练应用的代码可以按四类来读静态目录课程、模块、默认计划和徽章规则。用户状态收藏、训练记录、计划完成情况、主题、画像。页面状态当前 Tab、当前课程、搜索结果、训练计时和图解查看器。系统能力TTS、AVSession、后台任务、资源引用和构建安装。只要能把变量放回这四个桶里后续排查问题会容易很多。比如收藏丢失通常看持久化计时错乱通常看页面状态训练统计不准则回到训练记录。工程证据与可复现操作这部分不列作者电脑上的文件目录因为读者无法访问那些路径。更可复用的证据是页面截图、关键状态模型、核心代码片段和操作步骤。先从首页确认“今日推荐训练、计划入口、训练统计、收藏入口”是否形成闭环。再进入对应功能页观察截图中的按钮、列表、状态文案是否与代码片段描述一致。最后按“开始训练、完成记录、查看数据反馈”的顺序走一次主流程确认状态能同步到计划、数据和成就模块。可迁移到其他 HarmonyOS 项目的经验第一先把“静态内容”和“用户行为”分开。课程目录、默认计划、徽章定义和资源映射属于静态内容可以随着版本发布训练记录、收藏、主题、画像和计划完成状态属于用户行为必须能持久化、能恢复、能被统计。很多页面问题不是 ArkUI 写法本身造成的而是这两类数据混在一起后页面无法判断到底应该读模板还是读用户状态。第二页面状态要有明确生命周期。比如当前选中课程、是否展示搜索结果、是否进入主动训练、是否打开图解查看器这些都只是当前页面会话中的状态。它们不应该被保存成长期数据也不应该影响下一次打开应用后的默认体验。训练记录和收藏可以留下弹窗、缩放偏移、临时搜索词则应该在合适的返回或关闭动作里清理。第三技术文章要给读者留下验证路径。只写“实现了计划生成”说服力不够最好同时给出关键代码片段、真实截图、操作路径和验证命令。这样读者可以判断这个功能是已经落地的能力还是仍停留在方案设计。对于 CSDN 系列工程证据越清楚越容易被认为有原创性和实践价值。第四离线优先并不等于功能简陋。它更像是一种约束不依赖账号、不依赖服务端、不上传训练隐私、不用网络失败阻断核心流程。在这个约束下规则引擎、静态课程库、本地语音提示、本地报告和本地截图验收都可以形成完整体验。后续如果要接入云同步或 AI 能力也应该先保证离线闭环不被破坏。常见坑与规避方式只在 UI 里写课程文案导致搜索、计划、收藏、统计都拿不到结构化数据。完成训练后只改按钮状态没有生成 TrainingRecord数据页和成就墙无法同步。收藏保存整份课程对象课程目录更新后收藏列表出现旧字段或旧文案。主题切换只改页面背景忽略文字、边框、卡片、按钮和空状态。截图使用宣传图或旧图和当前源码实现对不上发布后读者无法复现。在文章里粘贴本机签名配置、证书路径或密码字段造成不必要的安全风险。发布到 CSDN 前的高质量检查标题保持统一格式足球口袋教练 HarmonyOS 离线应用实战03/20ArkUI 首页仪表盘搭建摘要包含“问题、实现、验证”三要素避免只写宣传语。文章内至少保留一张真实 App 截图和一个代码片段。不暴露本机签名密码、证书密码、API Key 或私有账号信息。如果提到 HarmonyOS API 行为优先补充官方文档链接避免只引用二手博客。如果截图更新优先使用当前运行中的真实 App 截图不使用商店宣传图冒充运行截图。高质量补强首页仪表盘的布局拆解与评分点首页文章容易被写成“这里用了 Row 和 Column”这种写法技术密度不够。更好的写法是把首页拆成信息架构、状态来源、布局约束和验证方法四个部分。首页区域展示内容状态来源设计目的顶部用户区问候语、头像、主题快捷入口用户画像、主题状态提醒当前用户身份并提供低成本设置入口今日推荐推荐课程、时长、难度、开始按钮当前计划、课程目录让用户不思考也能开始训练数据摘要连续打卡、今日训练、收藏课程训练记录、收藏列表给用户即时反馈能力说明离线使用、科学系统训练静态产品能力建立产品可信度底部导航训练、计划、数据、我的activeTab 页面状态保持核心模块可达在 ArkUI 中做首页不建议把所有卡片都当作独立装饰。更稳的方式是把首页当作一条任务流先告诉用户今天练什么再告诉用户最近完成了什么最后提供进入其他模块的入口。这样页面变长也不会乱因为每一段都服务同一个目标。State activeTab: number 0; Builder MainShell() { Column() { Stack() { if (this.activeTab 0) { this.TrainingHomePage() } else if (this.activeTab 1) { this.PlanPage() } else if (this.activeTab 2) { this.DataPage() } else { this.MinePage() } } this.BottomNav() } }这段代码的重点是“页面状态只控制页面切换”。首页本身不要直接承担计划生成、记录统计、主题持久化等所有职责否则后续每改一个模块都会影响首页。更好的做法是让首页读取已经归一化的摘要结果例如今日推荐课程、今日训练分钟数、收藏数量再把计算逻辑逐步迁移到服务函数。首页验收清单首屏是否能看到一个明确的开始训练入口。推荐卡片是否包含课程名、时长、难度和行动按钮。数据摘要是否来自真实记录而不是固定文案。主题切换后首页文字、卡片、按钮、边框是否一起变化。底部导航切换是否只改变内容区域不造成页面状态串台。这类拆解能补足 CSDN 高质量评分里对内容充实度、原创实践、图片和代码解释的要求。文章不只是贴代码而是解释为什么这样组织页面、如何验证页面、下一步如何拆分。小结用卡片、统计摘要和快捷入口构建训练 App 的第一屏 是这篇文章的主线。足球口袋教练这个项目的价值不在于一次性塞满所有功能而在于把训练内容、计划、记录、反馈和本地能力串成一个可运行闭环。读者照着这个思路做自己的训练类或知识类 App也能先跑出一个离线可用的 MVP再逐步拆分和增强。参考资料Huawei Developer ArkUI Application FrameworkHuawei Developer ArkUI State Management OverviewHuawei Developer ArkTS Components Reference
