HarmonyOS应用实战-启示散页-31-首次引导别挡住首屏把新手提示放到播种完成之后这不是把一个概念换个名字再讲一遍。本文从The_Book_of_Answers的现有代码出发先确认能证明的实现再说明 把“首次提示”放在种子完成之后并把已读状态作为一个独立的持久化事实。。读完后读者应该能判断这件事该落在哪一层、何时写入、失败时怎样回退而不是只得到一段看起来能跑的片段。先说明本文的代码边界项目结论写作定位当前代码事实 明确的扩展设计已核对事实入口 Ability 会先初始化 PreferencesStore再 await SeedLoader.run最后才 loadContent当前还没有引导页。本篇要补的边界把“首次提示”放在种子完成之后并把已读状态作为一个独立的持久化事实。主要 ownerOnboardingGate拟新增对照源码entry/src/main/ets/entryability/EntryAbility.etsentry/src/main/ets/services/SeedLoader.ets这张表很重要。它把“仓库已经具备的能力”和“为了本题建议新增的能力”分开写避免把设计草图误当成现状说明。现场症状不是一个 UI 小问题首屏刚挂载就允许点击抽取但默认题库与 currentDeckId 还未稳定提示层反而遮住了真实故障。 这类问题表面上通常只表现为一次点击无响应、列表顺序不对或重启后状态变化真正难点在于页面、服务、仓储和运行期信号各自只掌握一部分事实。若让最靠近按钮的组件兼任所有角色后续增加入口时一定会出现行为分叉。可以把本篇的问题链压缩为输入进入 → 规则判断 → 一次可追踪写入 → 相关页面刷新 → 重启后的恢复验证。任何一步没有明确 owner都会把故障留给下一个页面处理。先从已存在的代码找证据本篇不假定项目中已经存在OnboardingGate拟新增。已经存在、且应优先复用的事实是入口 Ability 会先初始化 PreferencesStore再 await SeedLoader.run最后才 loadContent当前还没有引导页。。对应源码位于entry/src/main/ets/entryability/EntryAbility.etsentry/src/main/ets/services/SeedLoader.ets。这意味着后续设计应接在既有Repository / Service / AppStorage的职责边界上而不是重新发明一条平行链路。例如AppStorage在当前工程里用于传递CurrentDeckId、LastDeckUpdateAt等轻量刷新信息完整题库、收藏和历史仍由仓储读写。这个分工能让页面重新进入、冷启动和跨入口调用得到同一份最终事实。源码摘录entry/src/main/ets/entryability/EntryAbility.ets// 否则 DeckPicker.aboutToAppear 读取空数据AppStorage 也无法触发 watch 刷新try{awaitPreferencesStore.init(ctx);awaitSeedLoader.run(ctx);}catch(err){hilog.error(DOMAIN,testTag,bootstrap failed: %{public}s,(errasError).message);}windowStage.loadContent(pages/Index,(err){if(err.code){hilog.error(DOMAIN,testTag,Failed to load the content. Cause: %{public}s,JSON.stringify(err));return;这段是本篇依赖的当前实现不是为了文章临时编造的接口。后面的代码若写为“设计示例”只能在这段既有边界之外补齐能力不能改写它已经承担的职责。按问题类型定位断点本题属于生命周期问题优先确认“谁先完成、谁后挂载”。入口 Ability 会先初始化 PreferencesStore再 await SeedLoader.run最后才 loadContent当前还没有引导页。说明启动链路已有一个明确顺序扩展时不能在页面先行读取尚未完成的持久化数据。对生命周期问题而言最值得保留的证据不是截图而是首次启动、热重进和异常恢复三条路径的最终数据一致性。先确认已有实现是否已经覆盖了本题的一部分。再把没有覆盖的部分写成可验证的扩展边界。最后用异常入口与重启结果反证这条边界没有停留在页面内存。本篇的决策先完成启动写入再计算是否展示关闭引导后只提交版本号。OnboardingGate拟新增的职责不是“替页面做完所有事”而是把本主题的判断集中到一个位置。它要接受可验证输入、调用已有服务或仓储、在成功后发布最小刷新信号它不应持有 ArkUI 组件、Sheet 开关、动画进度或临时文本框状态。层级应负责的事不应顺手做的事页面收集意图、展示结果、给出失败提示直接写 Preferences、拼接持久化结构OnboardingGate拟新增校验、规则、回退和一次业务提交保存组件引用、控制动画Repository / 现有 Service保存和读取稳定数据判断页面文案、Toast 内容AppStorage只通知相关 owner 重新读取保存整份业务对象数据契约先于页面文案本主题需要稳定的数据描述onboardingVersion: number只记录已读版本不保存页面展示状态。。字段越少后续越容易判断哪一个变化真的需要持久化。尤其是把“用户内容”“运行期刷新信号”“页面临时状态”混在同一个对象中时重启与回退的语义会立刻变得模糊。// 当前边界入口 Ability 会先初始化 PreferencesStore再 await SeedLoader.run最后才 loadContent当前还没有引导页。// 本段只描述需要守住的输入与输出不把页面状态写入持久化层。interfaceOnboardingGate拟新增Input{source:string;subjectId?:string;}这段模型刻意很小它只让服务知道入口来源和业务对象身份。页面的展开、动画、按钮禁用状态都不应该进入这个接口。// 设计示例仅在本篇所述能力落地时新增。classOnboardingGate拟新增{asyncexecute(input:OnboardingGate拟新增Input):Promisevoid{if(!input.source){thrownewError(entry source is required);}// 先校验再调用既有 Repository / Service不要在这里操作 ArkUI 组件。}}这个示例的重点不是新建一个类而是把校验、业务规则和 UI 回调分开。若项目没有这项扩展就不应把类名写进“已实现”清单。// 页面侧只提交意图成功后的刷新信号由业务服务发出。privateasynconConfirm():Promisevoid{awaitnewOnboardingGate拟新增().execute({source:page});// 不直接写 PreferencesStore也不把完整对象塞进 AppStorage。}页面只拥有交互时机。这样相同操作将来从快捷入口、恢复页或设置页触发时仍然只会走一套规则。验收口径 1. 无效输入在业务边界被拒绝并能回到可理解的页面状态。 2. 成功路径只产生一次持久化写入和一次相关刷新。 3. 重启后以 Repository 的结果为准不依赖页面内存。 4. 诊断输出不包含用户问题、答案全文或整份题库。rg-nOnboardingGate拟新增|onboardingVersion: number|AppStorageKeyD:\ProgramData\huawei\lesson\The_Book_of_Answersrg-nEntryAbilityD:\ProgramData\huawei\lesson\The_Book_of_Answers排查时先从 owner 与数据契约找起再回到页面调用点。只搜索按钮文本通常只能找到症状所在的位置。落地前的三次反向确认第一先问现有代码是否已经提供了更窄的能力可以复用。本篇已核对的事实是入口 Ability 会先初始化 PreferencesStore再 await SeedLoader.run最后才 loadContent当前还没有引导页。。如果直接绕开这条路径新功能会复制一份相近但不完全相同的校验与刷新逻辑。第二再问onboardingVersion: number只记录已读版本不保存页面展示状态。中哪些字段必须跨重启存在。只有能影响下一次启动、另一个入口或数据恢复的字段才需要进入仓储其余状态留在页面即可。这个判断能避免为了“方便刷新”而把临时 UI 对象写入全局状态。第三反过来构造一次失败把弹窗写在 aboutToAppear 最前面会把启动顺序变成不可观测的竞态。。若这条失败路径没有可解释的结果说明 owner 的职责仍然太模糊应该先补回退结果再考虑扩展交互。为什么不能在页面里直接兜底错误做法通常看起来很省事在点击回调里读原始数据、改几个字段、写入 Preferences再自己把本地State调成“成功”。它会在第一个入口中工作但外部拉起、返回页面、恢复页或另一个窗口不会复用这个回调。本篇应避免的风险是把弹窗写在 aboutToAppear 最前面会把启动顺序变成不可观测的竞态。。正确的判断标准不是“当前页面是否更新”而是“相同输入从任何入口进入后是否得到同一份持久化结果和同一条刷新语义”。验证要覆盖恢复而不只覆盖正常点击清数据首次启动、升级引导版本、种子恢复三条路径都必须先看到可用题库再看到提示。 建议按下面顺序执行从正常页面入口走一遍记录写入前后数据差异。给出空值、过期值或已删除 id确认在 owner 处失败而不是在 UI 深处崩溃。执行完成后离开并重新进入相关页面确认它通过仓储重新读取正确结果。重启应用后再次核对确认没有依赖上一次页面的内存状态。检查日志、截图和导出文本不包含用户问题、答案全文或整份题库。常见误判与处理方式现象首先检查处理方式页面更新但重启后恢复原样是否只改了State把最终写入收回到 Service / Repository多入口表现不同是否绕过OnboardingGate拟新增统一把输入归一化后交给一个 owner列表没有刷新写入后是否只有正确的刷新信号让订阅者重新拉取不共享可变大对象排障信息不够或泄露内容日志是否记录了正文只保留 id、数量、阶段与错误码取舍保持轻量但不牺牲可解释性The_Book_of_Answers是本地优先的轻量应用因此不需要为了单一需求引入庞大框架。合适的复杂度是一个清晰 owner、一个小契约、复用现有仓储与服务、一个可观察的刷新信号以及一组能覆盖重启和异常入口的验证步骤。这样既不会把规则散回 UI也不会把每个功能都做成难以维护的大模块。这里的“轻量”不等于省掉边界。只要一个功能会改变本地内容、影响多个页面或需要在发布后被解释它就应当留下最小的持久化事实与验证证据反之纯展示状态不应借机渗入 Repository。这个取舍比新增多少类更重要。小结本篇的关键不是类名而是这条边界先完成启动写入再计算是否展示关闭引导后只提交版本号。。只要继续坚持“页面提交意图、服务处理规则、仓储保存事实、AppStorage 只通知刷新”这个主题无论未来从首页、快捷入口还是恢复流程进入都不会再演变成多套不一致的临时写法。
