页面之间要共享「学了多少词」「选了哪个年级」这类状态,这个项目没有用 @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 个写入点各维护一次加减,漏一处就会出现「数字永远差一」的问题,而这种错误极难定位。

七个页面的订阅方式

不同页面需要的东西不一样,订阅方式也就分成了四种:

页面订阅的键方式用途
MainPageGRADE_NAME@StorageLink顶部标题显示年级
UnitListPageVERSION_CODE / GRADE_KEY@StorageLink + @Watch切年级后重载单元列表
UnitListPageSTATS_VERSION@StorageLink + @Watch进度变化后重建行组件
FavoritePageSTATS_VERSION@StorageLink + @Watch收藏增删后重取列表
HistoryPageSTATS_VERSION@StorageLink + @Watch新记录后重新分组
StatsDetailPageSTATS_VERSION@StorageLink + @Watch详情项变化后重算
MinePageGRADE_NAME / FIRST_USE_DATE@StorageLink直接显示
MinePage三个计数@StorageLink直接显示数字
MinePageSTATS_VERSION@StorageLink + @Watch重新调用 refreshStats
CardLearnPageTTS_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 的内部变化通过版本号被翻译成「可观察的变化」,这是整套机制里唯一一个绕不过去的间接层。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐