【共创稿事节】HarmonyOS7 元服务【拼词小达人】的 AppStorage 状态广播与页面刷新
页面之间要共享「学了多少词」「选了哪个年级」这类状态,这个项目没有用 @Provide/@Consume,也没有用全局事件总线,而是走 AppStorage:写的一方只有两个 service,读的一方是七个页面,中间没有任何回写。难点不在传递,而在于让页面知道「底层的 Map 变了」—— Map 不是可观察对象,@StorageLink 绑不上它,所以需要一个专门用来递增的计数器。
一条单向通道
Constants.ets 里有一张键名表,9 个键:
export class StoreKeys {
static readonly VERSION_CODE: string = 'selectedVersionCode';
static readonly GRADE_KEY: string = 'selectedGradeKey';
static readonly GRADE_NAME: string = 'selectedGradeName';
static readonly FIRST_USE_DATE: string = 'firstUseDate';
static readonly STATS_VERSION: string = 'statsVersion';
static readonly TTS_SPEAKING: string = 'ttsSpeaking';
static readonly LEARNED_COUNT: string = 'learnedCount';
static readonly MASTERED_COUNT: string = 'masteredCount';
static readonly COLLECTED_COUNT: string = 'collectedCount';
}
全项目 AppStorage.setOrCreate 一共出现 32 次,全部在 StorageService(24 次)和 TtsService(8 次)里。页面侧一次都没有 —— 七个页面里唯一的直接调用是 UnitListPage 的一处 AppStorage.get:
const gradeName: string = AppStorage.get<string>(StoreKeys.GRADE_NAME) ?? '';
这条约束是刻意维持的。页面想改数据只能调 service 的方法(toggleCollected、recordRead、saveSelectedGrade),service 改完 Map 再统一广播。反过来说,如果某个页面自己 setOrCreate 了 learnedCount,它就和 service 里的 Map 失去了对应关系,下一次 notifyStatsChange 会把它覆盖回去,页面上就会出现「刚加的一闪又变回去」。
九个键按性质可以分成三组:
| 键 | 值的性质 | 写入方 | 生命周期 |
|---|---|---|---|
VERSION_CODE / GRADE_KEY / GRADE_NAME | 用户选择的持久值 | saveSelectedGrade | 跨启动保留 |
FIRST_USE_DATE | 一次性时间戳 | ensureFirstUseDate | 只写一次 |
STATS_VERSION | 单调递增的信号量 | notifyStatsChange | 进程内累加 |
LEARNED_COUNT / MASTERED_COUNT / COLLECTED_COUNT | 从 Map 派生的计数 | notifyStatsChange | 每次统计变化重算 |
TTS_SPEAKING | 播放中的瞬时状态 | TtsService | 秒级 |
前两组的四个键在 init() 里从盘上取真值;STATS_VERSION 置 0;TTS_SPEAKING 置 false;三个计数先置 0,紧接着由 notifyStatsChange 重算覆盖。STATS_VERSION 是唯一一个不持久化、也不参与任何业务判断的键 —— 它的全部作用就是「变一下」,让订阅者知道该重读数据了。
初始化时的九个初始值
init() 先把 preferences 里的四个持久值读出来,然后一次性铺进 AppStorage:
async init(context: Context): Promise<void> {
this.pref = await preferences.getPreferences(context, 'en_ordmester');
const versionCode: string = await this.getString(PrefKeys.SELECTED_VERSION_CODE, '');
const gradeKey: string = await this.getString(PrefKeys.SELECTED_GRADE_KEY, '');
const gradeName: string = await this.getString(PrefKeys.SELECTED_GRADE_NAME, '');
const firstUseDate: number = await this.getNumber(PrefKeys.FIRST_USE_DATE, 0);
AppStorage.setOrCreate(StoreKeys.VERSION_CODE, versionCode);
AppStorage.setOrCreate(StoreKeys.GRADE_KEY, gradeKey);
AppStorage.setOrCreate(StoreKeys.GRADE_NAME, gradeName);
AppStorage.setOrCreate(StoreKeys.FIRST_USE_DATE, firstUseDate);
AppStorage.setOrCreate(StoreKeys.STATS_VERSION, 0);
AppStorage.setOrCreate(StoreKeys.TTS_SPEAKING, false);
AppStorage.setOrCreate(StoreKeys.LEARNED_COUNT, 0);
AppStorage.setOrCreate(StoreKeys.MASTERED_COUNT, 0);
AppStorage.setOrCreate(StoreKeys.COLLECTED_COUNT, 0);
await this.loadStats();
await this.loadHistory();
this.notifyStatsChange();
this.initialized = true;
}
九个键里四个是从盘上读的真值,五个是固定初始值。三个计数先给 0,紧接着 loadStats() 把 statsMap 填好,最后 notifyStatsChange() 把真实计数算出来写回去。这中间有一段极短的时间窗口,计数是 0 而 Map 已经有数据 —— 因为整个 init() 被 EntryAbility await 住,页面在它返回之前不会被挂载,所以这个窗口对外不可见。如果哪天有人把 init() 改成不 await,窗口就会暴露。
setOrCreate 而不是 set 也是有意的。set 在键不存在时不做任何事,而启动时 AppStorage 是空的,所有键都不存在。setOrCreate 是先有则改、无则建,适合「初始化」这个语义。
statsVersion 作为刷新信号
notifyStatsChange 是全项目的广播中心,只有 7 行:
private notifyStatsChange(): void {
const current: number = AppStorage.get<number>(StoreKeys.STATS_VERSION) ?? 0;
AppStorage.setOrCreate(StoreKeys.STATS_VERSION, current + 1);
// 同步刷新顶部统计数字,保证 MinePage 的 @StorageLink 立即可见
AppStorage.setOrCreate(StoreKeys.LEARNED_COUNT, this.getLearnedCount());
AppStorage.setOrCreate(StoreKeys.MASTERED_COUNT, this.getMasteredTotal());
AppStorage.setOrCreate(StoreKeys.COLLECTED_COUNT, this.getCollectedTotal());
}
前半段递版本号,后半段同步三个计数。这两件事解决的是两个不同问题。
版本号解决「列表内容变了但数组引用没变」。statsMap 是个 Map<string, UserWordStat>,@StorageLink 只能观察 AppStorage 里的值,观察不到 Map 内部的增删。UnitListPage 的 units 数组里的每个 UnitRowItem 都会在自己 build 时调 storage.getLearnedCountForWordIds(...) 现算进度,但 UnitRowItem 的 @Prop 一个都没变,框架不会重建它,进度条就停在旧值上。
计数推送解决「数字要立刻对」。MinePage 三张统计卡绑的是 learnedCount / masteredCount / collectedCount 三个 @StorageLink,这三个值本身是可观察的标量,只要 service 写进去,UI 就更新,不需要页面做任何事。
一次 notifyStatsChange 里做了三件 getXxxCount(),每个都是 O(n) 遍历 statsMap。学满 4423 词时是三次 4423 次迭代,单次调用在毫秒以下。recordRead 在 CardLearnPage 里每翻一张卡调一次,这个频率下不值得做增量计数 —— 增量计数要在 5 个写入点各维护一次加减,漏一处就会出现「数字永远差一」的问题,而这种错误极难定位。
七个页面的订阅方式
不同页面需要的东西不一样,订阅方式也就分成了四种:
| 页面 | 订阅的键 | 方式 | 用途 |
|---|---|---|---|
MainPage | GRADE_NAME | @StorageLink | 顶部标题显示年级 |
UnitListPage | VERSION_CODE / GRADE_KEY | @StorageLink + @Watch | 切年级后重载单元列表 |
UnitListPage | STATS_VERSION | @StorageLink + @Watch | 进度变化后重建行组件 |
FavoritePage | STATS_VERSION | @StorageLink + @Watch | 收藏增删后重取列表 |
HistoryPage | STATS_VERSION | @StorageLink + @Watch | 新记录后重新分组 |
StatsDetailPage | STATS_VERSION | @StorageLink + @Watch | 详情项变化后重算 |
MinePage | GRADE_NAME / FIRST_USE_DATE | @StorageLink | 直接显示 |
MinePage | 三个计数 | @StorageLink | 直接显示数字 |
MinePage | STATS_VERSION | @StorageLink + @Watch | 重新调用 refreshStats |
CardLearnPage | TTS_SPEAKING | @StorageLink | 切换朗读按钮形态 |

图:我的页面展示由状态广播驱动刷新的统计数据。
@StorageLink 必须给初值,这个初值只在键还不存在时起作用:
@StorageLink(StoreKeys.STATS_VERSION) @Watch('onStatsChanged') statsVersion: number = 0;
@StorageLink(StoreKeys.LEARNED_COUNT) learnedCount: number = 0;
写 = 0 不是把 AppStorage 里的值重置成 0,而是声明「这个属性的类型是 number,默认零值」。如果省略初值,ArkTS 编译期就会报错,运行时拿到的也是 undefined,${this.learnedCount} 会渲染成字符串 undefined。
@Watch 的回调在值变化后同步执行,参数是属性名,但项目里四个页面的回调都写成无参形式,因为它们要做的事跟具体值无关:
private onStatsChanged(): void {
this.loadItems();
}
UnitListPage 的 @Watch 有两个,一个管年级切换,一个管统计变化:
@StorageLink(StoreKeys.VERSION_CODE) @Watch('onGradeChanged') versionCode: string = '';
@StorageLink(StoreKeys.GRADE_KEY) @Watch('onGradeChanged') gradeKey: string = '';
@StorageLink(StoreKeys.STATS_VERSION) @Watch('onStatsChanged') statsVersion: number = 0;
@State units: UnitInfo[] = [];
private onGradeChanged(): void {
this.loadUnits();
}
两个 @Watch('onGradeChanged') 挂在两个属性上,切年级时 saveSelectedGrade 会连着写 VERSION_CODE 和 GRADE_KEY,回调会被触发两次,loadUnits 跑两遍。第二遍的结果与第一遍相同,是一次可以接受的重复 —— 要避免它就得在回调里判断「另一个键是否也已经更新」,那需要读 AppStorage 当前值,代码会从 4 行涨到 10 行。
列表重建的两种手段
onStatsChanged 在 UnitListPage 里只做一件事:
/** 学习进度变化时,强制刷新列表,让 UnitRowItem 重新读取 statsMap */
private onStatsChanged(): void {
// 通过重新赋值 units 触发 ForEach 重建,确保所有 UnitRowItem 重新计算进度
this.units = [...this.units];
}
[...this.units] 造了一个新数组,@State 的赋值检测到引用变化,ForEach 重新走一遍 diff。元素本身是同一批 UnitInfo 对象,所以 diff 时会认为「每个 key 都没变」,默认策略下不会重建子组件 —— 这也是为什么还要在 key 里塞版本号:
ForEach(this.units, (unit: UnitInfo) => {
ListItem() {
UnitRowItem({
unitEmoji: unit.topicEmoji,
unitTopic: unit.topic,
unitNo: unit.unitNo,
wordCount: unit.wordCount,
statsVersion: this.statsVersion,
versionCode: this.versionCode,
gradeKey: this.gradeKey,
onUnitClick: (uNo: number, uTopic: string) => {
this.onUnitClick(uNo, uTopic);
}
})
}
}, (unit: UnitInfo) => `${this.versionCode}_${this.gradeKey}_unit_${unit.unitNo}_v${this.statsVersion}`)
key 从 ${versionCode}_${gradeKey}_unit_${unitNo} 变成了末尾加 _v${statsVersion}。版本号一变,所有 key 都变,ForEach 认为「旧的全部消失、新的全部出现」,于是全部 UnitRowItem 被销毁重建,每个都会重新执行 getLearnedCount()。
这两手是一套组合:新数组触发 diff,新 key 触发重建。只做前者,进度条不动;只做后者,ForEach 的数据源还是旧引用,diff 阶段可能直接跳过。
UnitRowItem 内部把 statsVersion 声明成 @Prop 却完全没在 build 里用:
@Prop statsVersion: number = 0;
@Prop versionCode: string = '';
@Prop gradeKey: string = '';
versionCode 与 gradeKey 是 getLearnedCount() 拼 wordId 要用的,statsVersion 纯粹是「占位参数」。它的作用是让父组件在构造子组件时传进一个会变的值 —— 即便 key 策略失效,@Prop 变化也能触发子组件刷新。这是第二层保险,代价是多一个没被读的字段,读代码的人需要知道它存在的原因。
计数的双份存储
三个计数在系统里存在两份:statsMap 里的原始记录是唯一真相,AppStorage 里的三个整数是派生值。派生值存在的唯一理由是 MinePage 的三张统计卡要绑标量。
MinePage 同时用了两条通道:
@StorageLink(StoreKeys.STATS_VERSION) @Watch('onStatsChanged') statsVersion: number = 0;
@StorageLink(StoreKeys.LEARNED_COUNT) learnedCount: number = 0;
@StorageLink(StoreKeys.MASTERED_COUNT) masteredCount: number = 0;
@StorageLink(StoreKeys.COLLECTED_COUNT) collectedCount: number = 0;
private onStatsChanged(): void {
this.refreshStats();
}
private refreshStats(): void {
const storage = StorageService.getInstance();
this.learnedCount = storage.getLearnedCount();
this.masteredCount = storage.getMasteredTotal();
this.collectedCount = storage.getCollectedTotal();
}
三个计数已经由 notifyStatsChange 推过一遍了,@Watch 里又算了一遍并赋回同名属性。赋值给 @StorageLink 属性会同步写回 AppStorage,但值相同,不会触发新一轮刷新,所以不会死循环。
重复的理由在于「谁来负责刷新」这个问题的答案不唯一。notifyStatsChange 是推送方,refreshStats 是拉取方,两条路都能让数字对上。留着两条的代价是每次统计变化多跑三次遍历;收益是即便某次写入没人调 notifyStatsChange,页面自己也能在版本号变化时补上。aboutToAppear 里也调了 refreshStats() —— 那次是页面首次挂载、版本号还没变时的唯一一次拉取。
saveSelectedGrade 里也补了一次推送,虽然从数学上讲三个计数不会变:
async saveSelectedGrade(versionCode: string, gradeKey: string, gradeName: string): Promise<void> {
await this.pref?.put(PrefKeys.SELECTED_VERSION_CODE, versionCode);
await this.pref?.put(PrefKeys.SELECTED_GRADE_KEY, gradeKey);
await this.pref?.put(PrefKeys.SELECTED_GRADE_NAME, gradeName);
await this.pref?.flush();
AppStorage.setOrCreate(StoreKeys.VERSION_CODE, versionCode);
AppStorage.setOrCreate(StoreKeys.GRADE_KEY, gradeKey);
AppStorage.setOrCreate(StoreKeys.GRADE_NAME, gradeName);
AppStorage.setOrCreate(StoreKeys.LEARNED_COUNT, this.getLearnedCount());
AppStorage.setOrCreate(StoreKeys.MASTERED_COUNT, this.getMasteredTotal());
AppStorage.setOrCreate(StoreKeys.COLLECTED_COUNT, this.getCollectedTotal());
}
getLearnedCount() 统计的是整个 statsMap,与当前选了哪个年级无关,所以切年级前后这三个数字一模一样。三次遍历在这里是纯粹的空转。留着它的意义是让这个方法的副作用集完整 —— 调用方不需要知道「哪些值变了、哪些值没变」,只要调完就能保证 AppStorage 与 Map 一致。
哪些状态不该进 AppStorage
CardLearnPage 里有两个状态看起来跟全局有关,却没有进 AppStorage:
@State isCollected: boolean = false;
@State isMastered: boolean = false;
它们跟着当前卡片走,每次翻页由 refreshCardState 重算:
private refreshCardState(): void {
if (this.currentIndex >= 0 && this.currentIndex < this.words.length) {
const word = this.words[this.currentIndex];
const storage = StorageService.getInstance();
this.isCollected = storage.isCollected(word.id);
this.isMastered = storage.isMastered(word.id);
this.showMeaning = true;
}
}
如果这两个值放进 AppStorage,就必须为「每一张卡片的收藏态」各占一个键,或者用一个「当前 wordId 的收藏态」共享键 —— 后者会让卡片列表里 72 张卡的渲染都去读同一个键,翻页时全部跟着重建。放在 @State 里,只有当前卡的按钮状态变,其余卡片拿的是 index === this.currentIndex ? this.isCollected : false:
WordCard({
// ...
isCollected: index === this.currentIndex ? this.isCollected : false,
isMastered: index === this.currentIndex ? this.isMastered : false,
// ...
})
判断标准其实很直白:跨页面、跨进程都要读的值进 AppStorage;只在本页面生命周期内、只服务当前焦点项的值留 @State。statsVersion 属于前者(三个页面都要靠它刷新),isCollected 属于后者。
TTS_SPEAKING 是个边界案例。它由 TtsService 直接写,页面只读:
AppStorage.setOrCreate(StoreKeys.TTS_SPEAKING, true);
单独一个布尔值放在全局,是因为写它的是 service(在回调线程里),读它的是 WordCard(在 UI 树里),两边没有任何引用关系。CardLearnPage 只是把它转成 @StorageLink 再传给卡片:
@StorageLink(StoreKeys.TTS_SPEAKING) isSpeaking: boolean = false;
FavoritePage 里也有朗读按钮,却没订阅这个值 —— 收藏页只显示一个圆钮,没有「朗读中」形态,不需要知道播放状态。同一个全局键,只有真正需要它的页面才绑。
到这里,状态流转的三个环节都齐了:写入收敛在两个 service,广播靠一个递增的版本号加三个预计算的计数,读取分成绑值和绑回调两种。Map 的内部变化通过版本号被翻译成「可观察的变化」,这是整套机制里唯一一个绕不过去的间接层。
更多推荐
所有评论(0)