HarmonyOS应用实战-启示散页-31-首次引导别挡住首屏：把新手提示放到播种完成之后

HarmonyOS应用实战-启示散页-31-首次引导别挡住首屏：把新手提示放到播种完成之后

这不是把一个概念换个名字再讲一遍。本文从 The_Book_of_Answers 的现有代码出发，先确认能证明的实现，再说明 把“首次提示”放在种子完成之后，并把已读状态作为一个独立的持久化事实。。读完后，读者应该能判断这件事该落在哪一层、何时写入、失败时怎样回退，而不是只得到一段看起来能跑的片段。

先说明本文的代码边界

这张表很重要。它把“仓库已经具备的能力”和“为了本题建议新增的能力”分开写，避免把设计草图误当成现状说明。

现场症状不是一个 UI 小问题

首屏刚挂载就允许点击抽取，但默认题库与 currentDeckId 还未稳定，提示层反而遮住了真实故障。 这类问题表面上通常只表现为一次点击无响应、列表顺序不对或重启后状态变化；真正难点在于，页面、服务、仓储和运行期信号各自只掌握一部分事实。若让最靠近按钮的组件兼任所有角色，后续增加入口时一定会出现行为分叉。

可以把本篇的问题链压缩为：输入进入 → 规则判断 → 一次可追踪写入 → 相关页面刷新 → 重启后的恢复验证。任何一步没有明确 owner，都会把故障留给下一个页面处理。

先从已存在的代码找证据

本篇不假定项目中已经存在 OnboardingGate（拟新增）。已经存在、且应优先复用的事实是：入口 Ability 会先初始化 PreferencesStore，再 await SeedLoader.run，最后才 loadContent；当前还没有引导页。。对应源码位于 entry/src/main/ets/entryability/EntryAbility.ets；entry/src/main/ets/services/SeedLoader.ets。这意味着后续设计应接在既有 Repository / Service / AppStorage 的职责边界上，而不是重新发明一条平行链路。

例如，AppStorage 在当前工程里用于传递 CurrentDeckId、LastDeckUpdateAt 等轻量刷新信息；完整题库、收藏和历史仍由仓储读写。这个分工能让页面重新进入、冷启动和跨入口调用得到同一份最终事实。

源码摘录：entry/src/main/ets/entryability/EntryAbility.ets

// 否则 DeckPicker.aboutToAppear 读取空数据，AppStorage 也无法触发 watch 刷新
try {
await PreferencesStore.init(ctx);
await SeedLoader.run(ctx);
} catch (err) {
hilog.error(DOMAIN, 'testTag', 'bootstrap failed: %{public}s', (err as Error).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 开关、动画进度或临时文本框状态。

数据契约先于页面文案

本主题需要稳定的数据描述：onboardingVersion: number；只记录已读版本，不保存页面展示状态。。字段越少，后续越容易判断哪一个变化真的需要持久化。尤其是把“用户内容”“运行期刷新信号”“页面临时状态”混在同一个对象中时，重启与回退的语义会立刻变得模糊。

// 当前边界：入口 Ability 会先初始化 PreferencesStore，再 await SeedLoader.run，最后才 loadContent；当前还没有引导页。
// 本段只描述需要守住的输入与输出，不把页面状态写入持久化层。
interface OnboardingGate（拟新增）Input {
source: string;
subjectId?: string;
}

这段模型刻意很小：它只让服务知道入口来源和业务对象身份。页面的展开、动画、按钮禁用状态都不应该进入这个接口。

// 设计示例：仅在本篇所述能力落地时新增。
class OnboardingGate（拟新增） {
async execute(input: OnboardingGate（拟新增）Input): Promise<void> {
if (!input.source) {
throw new Error('entry source is required');
}
// 先校验，再调用既有 Repository / Service；不要在这里操作 ArkUI 组件。
}
}

这个示例的重点不是新建一个类，而是把校验、业务规则和 UI 回调分开。若项目没有这项扩展，就不应把类名写进“已实现”清单。

// 页面侧只提交意图；成功后的刷新信号由业务服务发出。
private async onConfirm(): Promise<void> {
await new OnboardingGate（拟新增）().execute({ source: 'page' });
// 不直接写 PreferencesStore，也不把完整对象塞进 AppStorage。
}

页面只拥有交互时机。这样相同操作将来从快捷入口、恢复页或设置页触发时，仍然只会走一套规则。

验收口径
1. 无效输入在业务边界被拒绝，并能回到可理解的页面状态。
2. 成功路径只产生一次持久化写入和一次相关刷新。
3. 重启后以 Repository 的结果为准，不依赖页面内存。
4. 诊断输出不包含用户问题、答案全文或整份题库。

rg –n "OnboardingGate（拟新增）|onboardingVersion: number|AppStorageKey" "D:\\ProgramData\\huawei\\lesson\\The_Book_of_Answers"
rg –n "EntryAbility" "D:\\ProgramData\\huawei\\lesson\\The_Book_of_Answers"

排查时先从 owner 与数据契约找起，再回到页面调用点。只搜索按钮文本，通常只能找到症状所在的位置。

落地前的三次反向确认

第一，先问现有代码是否已经提供了更窄的能力可以复用。本篇已核对的事实是：入口 Ability 会先初始化 PreferencesStore，再 await SeedLoader.run，最后才 loadContent；当前还没有引导页。。如果直接绕开这条路径，新功能会复制一份相近但不完全相同的校验与刷新逻辑。

第二，再问 onboardingVersion: number；只记录已读版本，不保存页面展示状态。 中哪些字段必须跨重启存在。只有能影响下一次启动、另一个入口或数据恢复的字段才需要进入仓储；其余状态留在页面即可。这个判断能避免为了“方便刷新”而把临时 UI 对象写入全局状态。

第三，反过来构造一次失败：把弹窗写在 aboutToAppear 最前面，会把启动顺序变成不可观测的竞态。。若这条失败路径没有可解释的结果，说明 owner 的职责仍然太模糊，应该先补回退结果，再考虑扩展交互。

为什么不能在页面里直接兜底

错误做法通常看起来很省事：在点击回调里读原始数据、改几个字段、写入 Preferences，再自己把本地 @State 调成“成功”。它会在第一个入口中工作，但外部拉起、返回页面、恢复页或另一个窗口不会复用这个回调。

本篇应避免的风险是：把弹窗写在 aboutToAppear 最前面，会把启动顺序变成不可观测的竞态。。正确的判断标准不是“当前页面是否更新”，而是“相同输入从任何入口进入后，是否得到同一份持久化结果和同一条刷新语义”。

验证要覆盖恢复，而不只覆盖正常点击

清数据首次启动、升级引导版本、种子恢复三条路径都必须先看到可用题库，再看到提示。 建议按下面顺序执行：

常见误判与处理方式

取舍：保持轻量，但不牺牲可解释性

The_Book_of_Answers 是本地优先的轻量应用，因此不需要为了单一需求引入庞大框架。合适的复杂度是：一个清晰 owner、一个小契约、复用现有仓储与服务、一个可观察的刷新信号，以及一组能覆盖重启和异常入口的验证步骤。这样既不会把规则散回 UI，也不会把每个功能都做成难以维护的大模块。

这里的“轻量”不等于省掉边界。只要一个功能会改变本地内容、影响多个页面或需要在发布后被解释，它就应当留下最小的持久化事实与验证证据；反之，纯展示状态不应借机渗入 Repository。这个取舍比新增多少类更重要。

小结

本篇的关键不是类名，而是这条边界：先完成启动写入，再计算是否展示；关闭引导后只提交版本号。。只要继续坚持“页面提交意图、服务处理规则、仓储保存事实、AppStorage 只通知刷新”，这个主题无论未来从首页、快捷入口还是恢复流程进入，都不会再演变成多套不一致的临时写法。