「已学」「已记住」「已收藏」是三个不同口径的数字,但它们的数据源是同一条 UserWordStat 记录。已学看 readCount > 0,已记住看 mastered,已收藏看 collected,三个布尔或计数的组合在一个 Map 里共存。三个数字点进去要能看明细,而明细页只有一个 —— 用 mode 参数在同一条渲染树里切三种形态。

一条记录五个字段

UserWordStat 是全部统计的唯一数据源,7 行:

export interface UserWordStat {
  wordId: string;
  readCount: number;
  lastReadTime: number;
  mastered: boolean;
  collected: boolean;
}

五个字段对应四种状态转换:

方法修改的字段新建时的初值
recordReadreadCount += 1、lastReadTime = nowreadCount: 1、lastReadTime: now
toggleCollectedcollected = !collectedreadCount: 0、lastReadTime: 0、collected: true
toggleMasteredmastered = !masteredreadCount: 0、lastReadTime: 0、mastered: true

三个方法在记录不存在时都会补一条,且补的时候只把自己那个字段设成目标值,其余给零值。所以一条记录最终长什么样,取决于用户对这个词做过哪些操作、按什么顺序做:

操作序列readCountlastReadTimemasteredcollected
只读过 3 次3最后一次时间falsefalse
只收藏00falsetrue
先收藏再读 2 次2最后时间falsetrue
先记住又取消00falsefalse

表格最后一行是个边界:toggleMastered 对已存在的记录只翻布尔值,不会删记录。所以「记住又取消」会留下一条全零记录 —— 它不计入任何统计(readCount 是 0、两个布尔都是 false),但会一直留在 statsMap 里,也一直参与每次 saveStats 的全量序列化。

三个计数的实现

三个总数都是全表遍历:

getLearnedCount(): number {
  let count: number = 0;
  this.statsMap.forEach((stat: UserWordStat) => {
    if (stat.readCount > 0) {
      count += 1;
    }
  });
  return count;
}

getMasteredTotal(): number {
  let count: number = 0;
  this.statsMap.forEach((stat: UserWordStat) => {
    if (stat.mastered) {
      count += 1;
    }
  });
  return count;
}

getCollectedTotal(): number {
  let count: number = 0;
  this.statsMap.forEach((stat: UserWordStat) => {
    if (stat.collected) {
      count += 1;
    }
  });
  return count;
}

三个方法名字不同、结构完全一样,只是判断条件不一样。getLearnedCount 判 readCount > 0,另外两个判布尔。三个都不看 repo,纯粹在 statsMap 上数。

getStat 是单个查询:

getStat(wordId: string): UserWordStat | undefined {
  return this.statsMap.get(wordId);
}

只有 StatsDetailPage 用它 —— 明细列表要显示每个词的 readCount 和 lastReadTime,而 getLearnedWordIds() 只返回 id。

isCollected / isMastered 是给单卡用的:

isCollected(wordId: string): boolean {
  const stat: UserWordStat | undefined = this.statsMap.get(wordId);
  if (stat) {
    return stat.collected;
  }
  return false;
}

不存在时返回 false 而不是 undefined,调用方(CardLearnPage.refreshCardState)可以直接赋给布尔型 @State。这两个方法比 getStat(wordId)?.collected ?? false 更啰嗦,但少一次空值判断。

列表口径与计数口径的偏差

getLearnedCount() 与 getLearnedWordIds() 是两个独立实现,理论上应该给出同样的数字(前者返回 n,后者返回长度 n 的数组)。但它们的过滤强度不同:

getLearnedWordIds(): string[] {
  const result: string[] = [];
  const arr: UserWordStat[] = [];
  this.statsMap.forEach((stat: UserWordStat) => {
    if (stat.readCount > 0) {
      arr.push(stat);
    }
  });
  arr.sort((a: UserWordStat, b: UserWordStat) => b.lastReadTime - a.lastReadTime);
  for (const s of arr) {
    result.push(s.wordId);
  }
  return result;
}

它按 lastReadTime 倒序排,排序是稳定的一次比较。getCollectedWordIds 与 getMasteredWordIds 不排序:

getCollectedWordIds(): string[] {
  const result: string[] = [];
  this.statsMap.forEach((stat: UserWordStat) => {
    if (stat.collected) {
      result.push(stat.wordId);
    }
  });
  return result;
}

顺序是 Map 的插入顺序,也就是「第一次被碰到的顺序」。收藏列表因此按「收藏(或首次阅读)先后」排,而不是按最近操作排 —— 一个三月收藏、五月又取消再收藏的词,位置还在三月的那个坑上,因为 Map.set 对已存在的键不改变插入顺序。

计数与列表的真正偏差出现在详情页:

private loadItems(): void {
  const storage = StorageService.getInstance();
  const repo = WordRepository.getInstance();

  let wordIds: string[] = [];
  if (this.mode === 'mastered') {
    wordIds = storage.getMasteredWordIds();
  } else if (this.mode === 'collected') {
    wordIds = storage.getCollectedWordIds();
  } else {
    wordIds = storage.getLearnedWordIds();
  }

  const result: DetailItem[] = [];
  for (const wordId of wordIds) {
    const word: WordInfo | undefined = repo.getWordById(wordId);
    if (!word) {
      continue;
    }
    const stat: UserWordStat | undefined = storage.getStat(wordId);
    result.push({
      wordId: wordId,
      wordText: word.text,
      wordMeaning: word.meaning,
      wordPhonetic: word.phonetic,
      readCount: stat ? stat.readCount : 0,
      lastReadTime: stat ? stat.lastReadTime : 0
    });
  }
  this.items = result;
}

if (!word) continue 是唯一会丢条目的地方。statsMap 里的 id 来自历史操作,allWords 里的 id 来自当前加载的词库 —— 只有当词库换了(比如应用升级后裁剪了词表),两边才会对不上。这时三个计数仍然把所有记录算进去,而详情页会跳过找不到的那些,出现「已学 12」但列表只有 10 条的情况。

stat ? stat.readCount : 0 这个三元也没必要 —— 能进 wordIds 的前提就是从 statsMap 里筛出来的,getStat 一定命中。写成三元是为了让类型收窄通过编译,运行时永远是第一个分支。

同一个页面三种形态

StatsDetailPage 通过路由参数拿到 mode:

@State mode: string = 'learned';

aboutToAppear(): void {
  const rawParams: Object = router.getParams();
  if (rawParams) {
    const params = rawParams as StatsDetailRouteParams;
    this.mode = params.mode;
  }
  this.loadItems();
}

StatsDetailRouteParams 只有一个字段,注释写明了取值范围:

已学单词详情

图:已学单词详情页。

已记住与已收藏单词详情

图:已收藏、已记住等统计状态的详情页。

export interface StatsDetailRouteParams {
  /** learned | mastered | collected */
  mode: string;
}

用 string 而不是联合字面量类型,是因为路由参数在跨页面传递时会退化成 Object,断言成联合类型也只是编译期的假象。默认值 'learned' 保证了参数缺失时页面仍然可用。

三个 mode 影响四处渲染。标题:

private getTitle(): string {
  if (this.mode === 'mastered') {
    return '已记住';
  } else if (this.mode === 'collected') {
    return '已收藏';
  }
  return '已学';
}

空状态文案:

private getEmptyMessage(): string {
  if (this.mode === 'mastered') {
    return '还没有已记住的单词';
  } else if (this.mode === 'collected') {
    return '还没有收藏的单词';
  }
  return '还没有已学的单词';
}

空状态图标,用嵌套三元写在参数里:

EmptyState({
  iconRes: this.mode === 'collected'
    ? $r('app.media.ic_empty_star')
    : this.mode === 'mastered'
      ? $r('app.media.ic_book_word')
      : $r('app.media.ic_empty_book'),
  messageStr: this.getEmptyMessage(),
  subMessageStr: this.getEmptySub()
})

以及右侧附加信息,只有「已学」显示:

if (this.mode === 'learned') {
  Column() {
    Text(`×${item.readCount}`)
      .fontSize(14)
      .fontWeight(FontWeight.Medium)
      .fontColor(AppColors.MINT_GREEN)
    if (item.lastReadTime > 0) {
      Text(GradeUtils.formatTimeAgo(item.lastReadTime))
        .fontSize(11)
        .fontColor(AppColors.TEXT_GRAY)
        .margin({ top: 4 })
    }
  }
  .alignItems(HorizontalAlign.End)
  .margin({ left: 8 })
}

×N 只在「已学」出现,因为只有这个口径与次数有关。已记住和已收藏是布尔状态,显示次数没有意义 —— 一个词被读 20 次然后记住,和读 1 次就记住,在「已记住」这个口径下没有区别。

三种形态的差异汇总:

元素learnedmasteredcollected
标题已学已记住已收藏
空状态图标ic_empty_bookic_book_wordic_empty_star
空状态文案还没有已学的单词还没有已记住的单词还没有收藏的单词
词条主体单词 + 音标 + 释义同左同左
右侧×N + 相对时间无无
排序lastReadTime 倒序Map 插入序Map 插入序

getHeaderSubtitle() 三种形态共用一行:

private getHeaderSubtitle(): string {
  return `共 ${this.items.length} 个单词`;
}

它取的是 items.length 而不是三个 getXxxTotal()。这样即便出现前面说的「计数 12、列表 10」,标题栏显示的也是 10 —— 页面内部自洽,与首页卡片上的数字可能差一点。

点击进来与点击出去

入口在 MinePage 的三张统计卡上:

@Builder
statCard($$: StatCardParam) {
  Column() {
    Image($$.iconRes)
      .width(IconSizes.STAT_CARD)
      .height(IconSizes.STAT_CARD)
      .margin({ bottom: 8 })
    Text(`${$$.count}`)
      .fontSize(28)
      .fontWeight(FontWeight.Bold)
      .fontColor(AppColors.MINT_GREEN)
    Text($$.label)
      .fontSize(13)
      .fontColor(AppColors.TEXT_GRAY)
      .margin({ top: 4 })
  }
  .width('30%')
  .padding({ top: 16, bottom: 16 })
  .backgroundColor(AppColors.CARD_BG)
  .borderRadius(AppSizes.CARD_RADIUS)
  .justifyContent(FlexAlign.Center)
  .alignItems(HorizontalAlign.Center)
  .onClick(() => {
    router.pushUrl({ url: 'pages/StatsDetailPage', params: { mode: $$.mode } });
  })
}

mode 通过 $$ 这个参数对象传进来:

this.statCard({ iconRes: $r('app.media.ic_book_learn'), label: '已学', count: this.learnedCount, mode: 'learned' })
this.statCard({ iconRes: $r('app.media.ic_book_word'), label: '已记住', count: this.masteredCount, mode: 'mastered' })
this.statCard({ iconRes: $r('app.media.ic_star_favorite'), label: '已收藏', count: this.collectedCount, mode: 'collected' })

$$ 是 ArkUI 里「按引用传递参数」的约定写法 —— 普通的 @Builder 参数是值传递,用它可以让 statCard 内部的 $$.count 跟随外部 @StorageLink 更新。三张卡的 label 与 mode 一一对应,但它们是两个独立的字符串,改一个忘了改另一个就会出现「点已学进去看到已收藏」。

详情页的返回按钮是一个旋转 180 度的右箭头:

Image($r('app.media.ic_arrow_right'))
  .width(IconSizes.ARROW)
  .height(IconSizes.ARROW)
  .fillColor(AppColors.TEXT_DARK)
  .rotate({ angle: 180 })
  .onClick(() => {
    router.back();
  })

资源里只有右箭头,左箭头靠 rotate 出。fillColor 把图标染成 TEXT_DARK,避免用另一份深色资源。

单元行的现场拼 id

单元列表里的进度是另一条统计路径,它不查任何「按单元聚合」的方法,而是自己拼 id:

private getLearnedCount(): number {
  const storage = StorageService.getInstance();
  if (this.wordCount === 0 || this.versionCode.length === 0 || this.gradeKey.length === 0) {
    return 0;
  }
  const wordIds: string[] = [];
  for (let i: number = 0; i < this.wordCount; i++) {
    wordIds.push(`${this.versionCode}_${this.gradeKey}_${this.unitNo}_${i}`);
  }
  return storage.getLearnedCountForWordIds(wordIds);
}

它依赖 wordId 的生成规则与 WordRepository 完全一致:${code}_${gradeKey}_${unitNo}_${index}。i 从 0 到 wordCount - 1 连续取,前提是这个单元的 words 数组下标正好是 0..length-1 —— 成立,因为 parseData 里就是按下标顺序 push 的。

这条路径的脆弱点在于「猜 id」:UnitRowItem 不持有词对象,只持有 wordCount,靠字符串拼接反查。它之所以能成立,是因为 WordRepository 与 StorageService 共享同一套 id 规则,而这个规则没有写在任何接口里,只写在这两处的模板字符串中。

getLearnedCountForWordIds 是限定范围的计数:

/** 统计一组单词中已学(readCount > 0)的数量,用于栏目列表进度条 */
getLearnedCountForWordIds(wordIds: string[]): number {
  let count: number = 0;
  for (const id of wordIds) {
    const stat: UserWordStat | undefined = this.statsMap.get(id);
    if (stat && stat.readCount > 0) {
      count += 1;
    }
  }
  return count;
}

它是 O(单元词数) 的 Map.get,不是 O(全表)。72 个词的单元就是 72 次哈希查找,比遍历整个 statsMap 快得多 —— 这也是为什么单元行不直接调 getLearnedCount()。

同类的还有一个 getMasteredCount(wordIds):

getMasteredCount(wordIds: string[]): number {
  let count: number = 0;
  for (const id of wordIds) {
    const stat: UserWordStat | undefined = this.statsMap.get(id);
    if (stat && stat.mastered) {
      count += 1;
    }
  }
  return count;
}

它没有任何调用点。单元行只显示「已学 / 总数」的进度条,没有「已记住 / 总数」的第二个进度。留着它不产生错误,只是同一个「按 id 集合统计」的需求被实现了两次(getMasteredCount 与 getLearnedCountForWordIds),条件只差一个字段 —— 如果要加单元级的掌握进度,用现成的这个方法就行。

收藏页是第四条路径

FavoritePage 不走 StatsDetailPage,它自己组装列表:

private loadCollectedWords(): void {
  const storage = StorageService.getInstance();
  const repo = WordRepository.getInstance();
  const wordIds: string[] = storage.getCollectedWordIds();
  this.collectedWords = repo.getWordsByIds(wordIds);
}

getCollectedWordIds() 拿 id,getWordsByIds() 换成词对象,8 行。与详情页同一件事,两处实现 —— 差别在于收藏页要多一个朗读按钮,详情页要多一个 ×N 与时间,所以没有合并。

收藏页面

图:收藏页独立展示已收藏单词。

它的刷新方式与另三个页面一致:

@StorageLink(StoreKeys.STATS_VERSION) @Watch('onStatsChanged') statsVersion: number = 0;

private onStatsChanged(): void {
  this.loadCollectedWords();
}

三个口径加一条单元级路径、一个详情页三态、一个收藏列表,统计这一层的形状就是这样。所有查询都建立在「一个词一条记录、记录里有三个独立状态」这个模型上 —— 这个模型简单到不需要任何聚合表,代价是每个聚合数字都要现场数一遍。

Logo

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

更多推荐