系列第 3 篇。本文讲数据层一个比赛工具要在没有账号、没有服务器、没有网络的情况下稳定记录对局、费用、比分和用户设置。一、真实问题背景羽毛球组局现场不适合复杂登录也不应该把比赛记录依赖在网络上。组织者真正关心的是刚输入的费用不要丢刚生成的对阵不要丢计分退到后台再回来还能看重启 App 后历史仍在。所以这个项目采用本地优先策略持久化用kit.ArkData的 Preferences页面响应式状态用AppStorage。Preferences 解决“下次启动还在”AppStorage 解决“当前页面立刻刷新”。二、目标与边界本文目标是拆解当前项目已经落地的数据模式1. 设置数据怎么恢复。2. 对局列表和对局详情怎么持久化。3. 费用计算的最近输入和结果怎么缓存。4. 为什么服务层要同时写 Preferences 和 AppStorage。边界是当前基础版不讲云同步、不讲多设备冲突合并、不讲账号体系。跨设备数据流转会作为后续路线图文章单独讨论“本地优先如何走向多端协同”。三、启动时先恢复本地数据在EntryAbility的onCreate中项目先初始化三个存储服务再把 Preferences 数据恢复到 AppStorage。SettingsStore.initPrefs(this.context); SettingsStore.hydrateFromPrefs(); SessionStore.initPrefs(this.context); SessionStore.hydrateFromPrefs(); FeeCalcService.initPrefs(this.context); FeeCalcService.hydrateFromPrefs();这段顺序很关键。页面加载前先恢复状态页面出现时读取到的是最新镜像而不是默认空数据。这样首页可以展示“我的对局”排名页能拿到当前对局费用页也能回填最近输入。四、设置数据小而稳定common/src/main/ets/storage/SettingsStore.ets管理昵称、深浅色、主题色、头像预设等设置。设置项数量不多但对体验影响很明显。static initPrefs(context: Context): void { SettingsStore.prefs preferences.getPreferencesSync(context, { name: settings_store }); } private static persistSetting(key: string, value: string): void { const p SettingsStore.prefs; if (p undefined) { return; } p.putSync(key, value); p.flush(); }保存设置时项目先写AppStorage再写 Preferences。前者让 UI 立即变化后者让下次启动仍然恢复。static saveThemeTone(tone: string): void { AppStorage.setOrCreatestring(SettingsStore.KEY_THEME_TONE, tone); SettingsStore.persistSetting(SettingsStore.KEY_THEME_TONE, tone); }五、对局数据列表与详情分开对局数据比设置复杂。一个SessionSummary用于首页列表一个SessionDetail保存参与人和每场比赛。项目把列表和详情分开持久化避免每次展示首页都处理完整大对象。核心文件是common/src/main/ets/storage/SessionStore.etsstatic readonly KEY_SESSIONS: string g_sessions; static detailKey(id: string): string { return g_session_detail_${id}; } private static persistSessions(): void { const sessions SessionStore.list(); SessionStore.persist(SessionStore.KEY_SESSIONS, JSON.stringify(sessions)); }创建对局时先调用PairingAlgorithm.generate生成比赛再同时写列表、详情和当前激活对局。const matches: MatchItem[] PairingAlgorithm.generate( draft.participants, draft.courtCount, draft.roundCount, draft.pairingMode ); AppStorage.setOrCreateSessionSummary[](SessionStore.KEY_SESSIONS, sessions); AppStorage.setOrCreateSessionDetail(SessionStore.detailKey(session.id), detail); SessionStore.persistSessions(); SessionStore.persistDetail(detail);六、响应式刷新里的一个细节ArkUI 中数组和对象状态很容易因为“原地修改”导致刷新不稳定。项目里更新列表时通常会先slice()复制再替换 AppStorage 中的值。例如保存比分后重新生成matches数组并写回详情。这种做法比直接push/splice更啰嗦但换来的是更可预测的 UI 刷新。对比赛工具来说比分和排名不能靠“退出再进页面”刷新必须在当前页面立刻更新。七、取舍与风险Preferences 适合轻量本地数据但它不是复杂关系型数据库。当前项目选择它是因为基础版目标是单机离线、低权限、低打扰。风险在于如果未来要做跨设备数据流转必须补同步层、版本号、冲突合并和删除标记不能把当前本地 key 直接当成云端协议。另一个风险是旧版本数据迁移。项目已经有一些兼容逻辑例如头像预设的 legacy hash、旧 scope key 迁移。后续每次新增字段都应该给默认值和恢复策略。八、验证命令构建验证 D:\HuaweiDevelopFormalStudy\DevEco Studio\tools\hvigor\bin\hvigorw.bat assembleHap --mode module -p productdefault --no-daemon验证时间2026-06-28。当前结果为BUILD SUCCESSFUL。功能验收应覆盖创建对局、录入比分、退出重进、查看排名、重置数据、切换主题。九、官方参考Preferences 属于 ArkData 能力API 行为应以 HarmonyOS ArkData 官方文档 为准。不同 SDK 版本对同步、异常和容量约束可能有细节差异正式发布前需要按目标 SDK 复核。十、工程验收清单- 启动时先 hydrate再加载首页。- 设置、费用、对局分别有独立存储服务。- 列表和详情分开保存减少首页读取压力。- 更新数组状态时先复制再写回。- 重置数据只清用户状态不破坏静态资源。- 后续跨设备能力不能直接复用本地 key 当同步协议。十一、小结本地优先不是“不做云”而是先保证没有网络也能完成核心流程。对羽毛球工具来说这比一开始就上账号和同步更贴近现场使用。等本地模型稳定后再做手机、平板、手表之间的数据流转风险会小很多。十二、下一篇衔接下一篇进入系统 AI 能力如何用 Core Speech Kit 给实时计分加上离线比分播报并在失败时不影响手动计分主流程。