学习数据存得很朴素:一张 preferences 表,六个键,其中两个键里塞的是整个 JSON 字符串 —— 所有词的学习记录序列化成一个数组,所有历史记录序列化成另一个数组。每次翻卡都重写一次完整的统计数组,这在 4423 个词的规模上是个明确的取舍:写入量随学习量线性增长,换来的是不需要为单条记录设计键名,也不需要处理「某个键写坏了但别的还好」这种部分失败。

单表六个键

表名 en_ordmester,键名集中在一个类里:

export class PrefKeys {
  static readonly SELECTED_VERSION_CODE: string = 'selected_version_code';
  static readonly SELECTED_GRADE_KEY: string = 'selected_grade_key';
  static readonly SELECTED_GRADE_NAME: string = 'selected_grade_name';
  static readonly FIRST_USE_DATE: string = 'first_use_date';
  static readonly WORD_STATS: string = 'word_stats';
  static readonly HISTORY: string = 'history_entries';
}

六个键分两类,形态完全不同:

键值类型形态谁写
selected_version_codestring单值,如 pepsaveSelectedGrade
selected_grade_keystring单值,如 grade_3_upsaveSelectedGrade
selected_grade_namestring单值,如 三年级上册saveSelectedGrade
first_use_datenumber毫秒时间戳ensureFirstUseDate
word_statsstringJSON 数组,每项是一个 UserWordStatsaveStats
history_entriesstringJSON 数组,上限 200 项saveHistory

前四个是标量,读写都简单。后两个是「把数组当字符串存」,这是这套设计的核心:preferences 的 value 支持 number、string、boolean、Array<number>、Array<string>、Array<boolean>、Uint8Array、object,但没有「对象数组」这一档。要用键值对存一张表,可选做法是按 wordId 派生键名(stat_${wordId}),或者整表序列化成一个字符串。这里选了后者。

选它的直接好处是原子性。整表要么全写进去,要么这次调用失败、上一次的内容原样保留;派生键名的做法会变成「N 个键各写一次」,中间失败就留下一半新一半旧。另一个好处是不需要维护键的清单 —— 清空数据只需写两次 '[]',不用遍历删键。

代价是每次改动都要重写全表。

全量序列化

saveStats 是唯一的写入函数:

private async saveStats(): Promise<void> {
  const arr: UserWordStat[] = [];
  this.statsMap.forEach((stat: UserWordStat) => {
    arr.push(stat);
  });
  const json: string = JSON.stringify(arr);
  await this.pref?.put(PrefKeys.WORD_STATS, json);
  await this.pref?.flush();
}

Map 转数组再序列化,两步都是全量。序列化出来的每一项长这样:

{"wordId":"pep_grade_3_up_1_0","readCount":3,"lastReadTime":1750492800000,"mastered":false,"collected":false}

一条约 100 字节。写入量的上限不是词库的 4423,而是 statsMap 的实际条目数 —— 只有被 recordRead、toggleCollected、toggleMastered 碰过的词才会进这个 Map:

触发方式何时发生产生的条目
recordReadCardLearnPage 每翻一张卡、aboutToAppear、onFinishreadCount 从 0 起
toggleCollected点收藏按钮,词此前不存在collected: true,其余零值
toggleMastered点记住了按钮,词此前不存在mastered: true,其余零值

三个方法在词不存在时都会补一条新记录,所以「先收藏再读」和「先读再收藏」最终都落到同一条上 —— 差别只在于 collected 与 readCount 的初始值。这是 Map<string, UserWordStat> 按 wordId 去重的结果:一个词在表里永远只有一条。

flush() 紧跟 put() 之后。put 只更新内存中的副本,flush 才落盘。两个都 await,因为调用方需要知道「已经落盘了」这件事 —— 尤其是 clearAllStats 之后紧接着跳转页面,如果不保证落盘,跳到年级选择页时数据可能还在内存里没写出去。

saveHistory 结构一样,只是没有 Map 转换:

private async saveHistory(): Promise<void> {
  const json: string = JSON.stringify(this.historyList);
  await this.pref?.put(PrefKeys.HISTORY, json);
  await this.pref?.flush();
}

this.pref?. 的 ?. 不是随手写的。pref 的类型是 preferences.Preferences | null,在 init 完成前是 null。三个写入方法都是 async,理论上可以在 init 之前被调用 —— 那时 ?. 让整句变成空操作,不抛异常也不写任何东西,方法正常返回。这是一种「静默降级」:调用方不会收到错误,但数据也没进去。页面侧不会遇到这种情况,因为 EntryAbility 把 init 挡在前面;卡片进程走 FormAbility.initData,也有 isInitialized() 在前面。

读回时的两级校验

读取分两层:先按类型读出,再解析 JSON。第一层是两个小工具函数:

private async getString(key: string, defaultValue: string): Promise<string> {
  if (!this.pref) {
    return defaultValue;
  }
  const raw = await this.pref.get(key, defaultValue);
  if (typeof raw === 'string') {
    return raw;
  }
  return defaultValue;
}

private async getNumber(key: string, defaultValue: number): Promise<number> {
  if (!this.pref) {
    return defaultValue;
  }
  const raw = await this.pref.get(key, defaultValue);
  if (typeof raw === 'number') {
    return raw;
  }
  return defaultValue;
}

pref.get() 的返回类型是 preferences.ValueType,一个联合类型。直接 as string 也能过编译,但运行时会拿到 undefined 或数字,后面拼字符串就会出现 undefined 字样。typeof 检查把「键被别处写成了别的类型」这种情况也接住了 —— 比如某次版本迭代把 first_use_date 从字符串改成数字,老数据读出来是字符串,getNumber 会返回默认值 0 而不是把它硬转成 NaN。

第二层是 JSON.parse,包在 try/catch 里:

private async loadStats(): Promise<void> {
  const json: string = await this.getString(PrefKeys.WORD_STATS, '[]');
  try {
    const rawStats = JSON.parse(json) as UserWordStat[];
    if (Array.isArray(rawStats)) {
      for (const stat of rawStats) {
        this.statsMap.set(stat.wordId, stat);
      }
    }
  } catch (e) {
    this.statsMap.clear();
  }
}

三层防护叠在一起。getString 的默认值 '[]' 保证键不存在时拿到的是合法 JSON;Array.isArray 挡住「值是合法 JSON 但不是一个数组」(比如被写成 '{}');catch 挡住「值不是 JSON」(比如被写成空串或被截断)。三种情况的结果不同:前两种会走正常流程并得到一个空表,第三种清空 statsMap。

loadHistory 完全对称:

private async loadHistory(): Promise<void> {
  const json: string = await this.getString(PrefKeys.HISTORY, '[]');
  try {
    const rawHistory = JSON.parse(json) as HistoryEntry[];
    if (Array.isArray(rawHistory)) {
      this.historyList = rawHistory;
    }
  } catch (e) {
    this.historyList = [];
  }
}

loadHistory 用整体赋值而不是逐条 push,因为 historyList 是个数组不是 Map,直接换引用最简单。loadStats 必须逐条 set,因为要从 stat.wordId 里取出键。

JSON.parse 出来的对象是普通对象,as UserWordStat[] 只是编译期断言,运行时没有校验字段。所以一份手工改坏的数据(少一个 readCount)能顺利进 statsMap,然后 stat.readCount > 0 得到 false(undefined > 0),这一条就被算成「未学」。这类脏数据不会让程序崩,只会让某个统计数字偏低。

三个清空操作

三个清空方法的实现各不相同,差别在于「清什么」和「走哪条写入路径」。

clearHistory 最直接:

async clearHistory(): Promise<void> {
  this.historyList = [];
  await this.pref?.put(PrefKeys.HISTORY, '[]');
  await this.pref?.flush();
  this.notifyStatsChange();
}

没有调 saveHistory(),而是直接把字面量 '[]' 写进去。两种做法结果完全一样(JSON.stringify([]) 就是 '[]'),省掉的是一次 Map 转换和一次序列化。notifyStatsChange() 也要调 —— 历史页绑的是 statsVersion,不递增就不会重新分组。

clearFavorites 保留 statsMap 的条目,只把 collected 置 false:

清空收藏确认弹窗

图:批量清空收藏前的确认交互。

async clearFavorites(): Promise<void> {
  this.statsMap.forEach((stat: UserWordStat) => {
    stat.collected = false;
  });
  await this.saveStats();
  this.notifyStatsChange();
}

这里 await 了 saveStats()。对比 toggleCollected 里的调用:

toggleCollected(wordId: string): boolean {
  const existing: UserWordStat | undefined = this.statsMap.get(wordId);
  let newCollected: boolean;
  if (existing) {
    existing.collected = !existing.collected;
    newCollected = existing.collected;
  } else {
    const stat: UserWordStat = {
      wordId: wordId,
      readCount: 0,
      lastReadTime: 0,
      mastered: false,
      collected: true
    };
    this.statsMap.set(wordId, stat);
    newCollected = true;
  }
  this.saveStats();
  this.notifyStatsChange();
  return newCollected;
}

saveStats() 前面没有 await,toggleCollected 也不是 async。写盘是后台进行的,调用方立刻拿到新的布尔值用于更新按钮状态。这对点击按钮没问题 —— 用户不等落盘,UI 已经变了。但如果用户点完收藏立刻杀进程,最后那次写可能没完成。

clearFavorites 必须 await,因为它是「批量操作 + 立刻跳转/刷新」的组合:MinePage 的确认对话框里写了 .then(() => this.refreshStats()),如果不 wait 到落盘完成,refreshStats 读到的是内存(已正确),但页面重进时可能拿到旧数据。两种调用的差异不是风格问题,而是「调用方是否依赖写盘已完成」。

clearAllStats 是所有键一起归零:

清空所有数据确认弹窗

图:清空全部学习数据前的确认交互。

async clearAllStats(): Promise<void> {
  this.statsMap.clear();
  this.historyList = [];
  await this.pref?.put(PrefKeys.WORD_STATS, '[]');
  await this.pref?.put(PrefKeys.HISTORY, '[]');
  await this.pref?.put(PrefKeys.SELECTED_VERSION_CODE, '');
  await this.pref?.put(PrefKeys.SELECTED_GRADE_KEY, '');
  await this.pref?.put(PrefKeys.SELECTED_GRADE_NAME, '');
  await this.pref?.put(PrefKeys.FIRST_USE_DATE, 0);
  await this.pref?.flush();

  AppStorage.setOrCreate(StoreKeys.VERSION_CODE, '');
  AppStorage.setOrCreate(StoreKeys.GRADE_KEY, '');
  AppStorage.setOrCreate(StoreKeys.GRADE_NAME, '');
  AppStorage.setOrCreate(StoreKeys.FIRST_USE_DATE, 0);

  this.notifyStatsChange();
}

六个 put 之后只有一次 flush。put 改的是内存副本,一次 flush 把这批改动一起落盘,比每个键后各来一次 flush 少五次 IO。AppStorage 侧只重置四个「选择类」键,三个计数交给 notifyStatsChange 重算(此时 statsMap 已空,算出来都是 0)。statsVersion 不重置 —— 它是单调递增的信号量,重置回 0 会让所有页面的 @Watch 误判成「值变小了但还是一次变化」,语义上没必要。

AppStorage 与 preferences 在这段代码里是两套独立的状态,必须手动保持一致。六次 put 之后紧接着四次 setOrCreate,两组一一对应(除了 WORD_STATS / HISTORY 没有对应的 AppStorage 键)。

历史记录的截断与去重

addHistory 是唯一在业务层做数据结构维护的方法:

addHistory(wordId: string): void {
  const now: number = Date.now();
  const existing: HistoryEntry | undefined = this.historyList.find((entry: HistoryEntry) => entry.wordId === wordId);
  if (existing) {
    existing.timestamp = now;
    this.historyList = this.historyList.filter((entry: HistoryEntry) => entry.wordId !== wordId);
    const newEntry: HistoryEntry = { wordId: wordId, timestamp: now };
    this.historyList.unshift(newEntry);
  } else {
    const newEntry: HistoryEntry = { wordId: wordId, timestamp: now };
    this.historyList.unshift(newEntry);
  }
  if (this.historyList.length > 200) {
    this.historyList = this.historyList.slice(0, 200);
  }
  this.saveHistory();
  this.notifyStatsChange();
}

historyList 的契约是「按时间倒序、每个词只出现一次」。达成方式是三步:先 find 判断是否已存在,存在则改 timestamp 再用 filter 把它摘掉,最后无论新旧都 unshift 到头部。existing.timestamp = now 这一步其实不影响结果 —— 紧接着 filter 就把这个对象从数组里剔了,新 unshift 的是一个新对象。它存在的意义只在于「如果 filter 之后没有 unshift,时间戳也已经更新」,属于防御性写法。

200 是硬上限,slice(0, 200) 从头部截。截断发生在 unshift 之后,所以刚进的词一定在保留范围内,被丢掉的是最老的那条。

saveHistory() 与 notifyStatsChange() 都没有 await。历史页靠 statsVersion 刷新,读的是内存里的 historyList,与落盘无关 —— 只要内存对了,页面就对了。CardLearnPage 里 recordRead 和 addHistory 是连着调的两个同步方法:

private recordCurrentRead(): void {
  if (this.currentIndex >= 0 && this.currentIndex < this.words.length) {
    const word = this.words[this.currentIndex];
    const storage = StorageService.getInstance();
    storage.recordRead(word.id);
    storage.addHistory(word.id);
  }
}

一次翻卡会触发两次全量写:saveStats 写整个统计表,saveHistory 写整个历史表,各自带一次 flush。单单元 72 词学完就是 72 次翻页 × 2 次写盘。这个频率下没做合并,因为合并需要引入延迟写入和脏标记,而现有的写入量(几十 KB)在闪存上耗时可忽略。

getHistory() 返回的是内部数组的引用,不是拷贝:

getHistory(): HistoryEntry[] {
  return this.historyList;
}

返回的是内部数组的引用,不是拷贝。FormAbility 拿它遍历反推候选词,HistoryPage 拿它分组,两处都只读不写。但类型上它是可写的 —— 任何调用方 push 一个元素都不会触发落盘,也不会递增 statsVersion,造成内存与盘上数据不一致。要防住这一点得返回 [...this.historyList],代价是每次调用复制 200 个对象。这里选了不防,靠调用方自律。

为什么不用文件

词库用的是 getRawFileContent 读文件,学习数据用的是 preferences,两套不同的存储。区别在于读写模式:

维度preferencesfileIo 写 JSON
当前用法六个键,整表序列化成字符串单个 JSON 文件
写入方式put + flush打开、写入、关闭
原子性由框架保证单键需要自己写临时文件再重命名
读取方式await get(key)读全量字节再解码
适合的规模单值小、整体不大大文件、流式读写

这个项目的数据量级是「几百条记录、几十 KB」,preferences 的 get / put 直接对上了需求,不需要自己处理文件句柄、编码、临时文件、重命名这几步。词库是 950KB 的只读资源,性质完全不同,用 rawfile 才是对的。

如果学习记录涨到上万条,全量序列化的成本会变得显眼:一次翻页要序列化上万条记录、写几十万字节。那时该换成「按 wordId 分文件」或者干脆迁到关系型存储,用 UPDATE 只改一行。现在这个体量,全量写是对的 —— 它把「一致性」这件事交给了「一次 put」这个原子操作,代码里不需要任何事务逻辑。

数据层的全貌就是这些:一张表、六个键、两处 JSON 序列化、三个清空入口、一套读写各两步的校验。上层看到的是一堆同步的 getXxxCount() 和 isXxx(wordId),异步只出现在初始化和清空这两类操作上。

Logo

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

更多推荐