词库里写的是「三年级上册」,代码里流转的是 grade_3_up,界面上又要变回「三年级上册」。这三次形态转换全部收在一个 98 行的工具类里,同一份文件还负责四种时间格式:相对时间、完整日期、分组键、天数差。这些函数没有状态、没有依赖,输入输出都是字符串或数字,是整份代码里最容易单独读懂的一块。

中文数字到机器键

normalizeGradeKey 把词库里的原始年级名转成稳定的键:

static normalizeGradeKey(grade: string): string {
  let gradeNum: number = 0;
  if (grade.includes('一')) {
    gradeNum = 1;
  } else if (grade.includes('二')) {
    gradeNum = 2;
  } else if (grade.includes('三')) {
    gradeNum = 3;
  } else if (grade.includes('四')) {
    gradeNum = 4;
  } else if (grade.includes('五')) {
    gradeNum = 5;
  } else if (grade.includes('六')) {
    gradeNum = 6;
  }
  const isUp: boolean = grade.includes('上');
  return `grade_${gradeNum}_${isUp ? 'up' : 'down'}`;
}

六个 if/else if 依次判中文数字,上下午由「上」字判断。输出格式 grade_{n}_{up|down}。

这段逻辑依赖两个字符事实。第一,一到六的中文数字在「X年级」这种写法里互不包含 —— 「三年级上册」里只有「三」,不会误命中「一」或「二」。第二,「上」与「下」互斥,includes('上') 为假就是下册。

gradeNum 的初值是 0。如果传入的年级名里一个中文数字都没有(比如「预备班」),结果是 grade_0_down。这个兜底不会在这份数据上触发 —— 40 个年级名全是标准写法 —— 但它意味着「未知年级」和「一年级下册」会被分到不同的键,不会撞车。

反方向是 gradeKeyToDisplay:

static gradeKeyToDisplay(key: string): string {
  const parts: string[] = key.split('_');
  if (parts.length < 3) {
    return key;
  }
  const num: number = parseInt(parts[1], 10);
  const isUp: boolean = parts[2] === 'up';
  const numChars: string[] = ['', '一', '二', '三', '四', '五', '六'];
  const numChar: string = num >= 1 && num <= 6 ? numChars[num] : String(num);
  return `${numChar}年级${isUp ? '上册' : '下册'}`;
}

split('_') 得到 ['grade', '3', 'up'],三段。parts.length < 3 说明这个字符串不是合法的键(可能是原始年级名直接传进来了),原样返回 —— 这比抛异常或返回空串更有用,界面上至少还能看到一个字符串。

numChars 数组的下标 0 是空串,所以 numChars[num] 对 1 到 6 直接命中。超出范围(grade_0_down)走 String(num),显示成「0年级下册」。这个降级结果不好看,但它只在数据异常时出现,比显示空白可诊断。

这个函数在两处被调用:

调用点输入来源用途
GradeSelectPageg.gradeKey三列 Grid 里的年级按钮文字
GradeSelectPage.startLearning用户选中的 gradeKeygrades.find 失败时的后备年级名

startLearning 里的用法是 gradeInfo ? gradeInfo.grade : GradeUtils.gradeKeyToDisplay(...) —— 优先用词库里的原始名(三年级上册),拿不到才反推。两种来源的字符串在这份数据上完全一致,但原始名可能带额外信息(比如某些教材会写「三年级上册(新版)」),反推会丢掉后缀。

isGradeUp 与 getGradeNumber 是两个拆开的取数函数:

static isGradeUp(key: string): boolean {
  return key.includes('_up');
}

static getGradeNumber(key: string): number {
  const parts: string[] = key.split('_');
  if (parts.length < 3) {
    return 0;
  }
  return parseInt(parts[1], 10);
}

isGradeUp 用 includes('_up') 而不是 endsWith('_up'),两者在这份数据上等价。getGradeNumber 有两处保护:段数不足返回 0,parseInt 遇到非数字返回 NaN。实际上如果段数够而第二段不是数字,会返回 NaN,这个值再参与比较会全部为假 —— 不会崩,但会得到意外的排序。两个函数目前都没有调用点。

相对时间五档

formatTimeAgo 是历史列表和详情页右侧显示的时间:

学习历史页面

图:学习历史页面使用相对时间展示学习记录。

static formatTimeAgo(timestamp: number): string {
  if (timestamp <= 0) {
    return '很久以前';
  }
  const now: number = Date.now();
  const diff: number = now - timestamp;
  const oneMinute: number = 60 * 1000;
  const oneHour: number = 60 * oneMinute;
  const oneDay: number = 24 * oneHour;

  if (diff < oneMinute) {
    return '刚刚';
  } else if (diff < oneHour) {
    const minutes: number = Math.floor(diff / oneMinute);
    return `${minutes}分钟前`;
  } else if (diff < oneDay) {
    const hours: number = Math.floor(diff / oneHour);
    return `${hours}小时前`;
  } else if (diff < 7 * oneDay) {
    const days: number = Math.floor(diff / oneDay);
    return `${days}天前`;
  } else {
    const date: Date = new Date(timestamp);
    const month: number = date.getMonth() + 1;
    const day: number = date.getDate();
    return `${month}月${day}日`;
  }
}

五档的边界与输出:

时间差输出精度
<= 0(无效时间戳)很久以前—
< 1 分钟刚刚不分档
1 分钟 ~ 1 小时N分钟前分钟
1 小时 ~ 1 天N小时前小时
1 天 ~ 7 天N天前天
>= 7 天M月D日日期

三处 Math.floor 让时间只减不增:「59 分 59 秒」显示「59分钟前」,下一秒变「1小时前」,不会出现「60分钟前」。「23 小时 59 分」显示「23小时前」,然后跳到「1天前」。

timestamp <= 0 的兜底对应 UserWordStat 里 lastReadTime: 0 那条 —— 只收藏没读过的词,时间字段是 0,详情页如果显示成「1970年1月1日」会很怪。StatsDetailPage 里另有 if (item.lastReadTime > 0) 挡住这一行,所以「很久以前」这个分支实际上也走不到,是双保险。

超过 7 天之后输出不带年份。这在跨年时会丢失信息 —— 去年 3 月 5 日和今年 3 月 5 日都显示「3月5日」。历史页的分组头补上了这一层:

const dateLabel: string = GradeUtils.formatDate(entry.timestamp);

formatDate 带年份:

static formatDate(timestamp: number): string {
  const date: Date = new Date(timestamp);
  const year: number = date.getFullYear();
  const month: number = date.getMonth() + 1;
  const day: number = date.getDate();
  return `${year}年${month}月${day}日`;
}

所以列表项显示「3月5日」、分组头显示「2025年3月5日」,年份信息由分组头承担。一个信息只在最近的地方显示一次,是这个页面排版的基本规则。

分组键与分组顺序

formatDateKey 是分组的依据:

static formatDateKey(timestamp: number): string {
  const date: Date = new Date(timestamp);
  const year: number = date.getFullYear();
  const month: number = date.getMonth() + 1;
  const day: number = date.getDate();
  return `${year}-${month}-${day}`;
}

与 formatDate 同源,只是分隔符换成连字符。没有补零 —— 2026-1-5 而不是 2026-01-05。

不补零的后果是字符串排序不等于时间排序:'2026-10-1' < '2026-2-1' 在字典序上成立,但日期上不成立。如果分组依赖排序,这会出错;这个页面不依赖排序,因为顺序来自插入:

private loadHistory(): void {
  const storage = StorageService.getInstance();
  const repo = WordRepository.getInstance();
  const entries: HistoryEntry[] = storage.getHistory();

  const groups: Map<string, HistoryGroup> = new Map<string, HistoryGroup>();

  for (const entry of entries) {
    const word: WordInfo | undefined = repo.getWordById(entry.wordId);
    const dateKey: string = GradeUtils.formatDateKey(entry.timestamp);
    const dateLabel: string = GradeUtils.formatDate(entry.timestamp);

    let group: HistoryGroup | undefined = groups.get(dateKey);
    if (!group) {
      group = {
        dateKey: dateKey,
        dateLabel: dateLabel,
        items: []
      };
      groups.set(dateKey, group);
    }

    group.items.push({
      wordId: entry.wordId,
      timestamp: entry.timestamp,
      wordText: word ? word.text : '未知单词',
      wordMeaning: word ? word.meaning : ''
    });
  }

  const groupList: HistoryGroup[] = [];
  groups.forEach((group: HistoryGroup) => {
    groupList.push(group);
  });
  this.historyGroups = groupList;
}

顺序链条是这样的:historyList 按 timestamp 倒序(addHistory 每次 unshift,见存储那篇),遍历时最先遇到的是最新的记录,所以 Map 里第一个被创建的键就是最新的日期。Map 保留插入顺序,forEach 按插入顺序输出,groupList 天然是「最新日期在前」。

组内顺序同样来自遍历顺序 —— 同一个日期下,先遇到的先 push,也就更新。所以不需要任何 sort。

这段代码里有一处可以简化却没简化:dateLabel 在循环内部每次都算,而它只在新组创建时用得上。一个日期下有 10 条记录,formatDate 就会执行 10 次,其中 9 次的结果被丢弃。要省这点开销得先 groups.get(dateKey) 再决定要不要算 label,代码会多一个分支。200 条记录的上限下,这点开销没有意义。

'未知单词' 的兜底对应 repo.getWordById 找不到的情况 —— 词库换了之后,旧 wordId 在 allWords 里查不到。这时列表仍然显示一行,单词位置写「未知单词」,释义留空(wordMeaning 是空串时 build 里的 if (item.wordMeaning.length > 0) 会跳过整行)。

分级渲染

分组结果交给 ListItemGroup:

List({ space: 16 }) {
  ForEach(this.historyGroups, (group: HistoryGroup) => {
    ListItemGroup({ header: this.historyHeader(group.dateLabel, group.items.length) }) {
      ForEach(group.items, (item: HistoryWordItem) => {
        ListItem() {
          Row() {
            // ...
          }
        }
      }, (item: HistoryWordItem) => `${item.wordId}_${item.timestamp}`)
    }
  }, (group: HistoryGroup) => group.dateKey)
}

两层 ForEach,外层按 dateKey,内层按 wordId_timestamp。内层 key 拼上时间戳,是因为同一个词有可能在不同日期出现 —— 虽然 addHistory 里去重了(每个词只保留最新一条),所以实际上 wordId 已经唯一。拼时间戳是冗余的保险。

分组头用 @Builder:

@Builder
historyHeader(dateLabel: string, count: number) {
  Row() {
    Text(dateLabel)
      .fontSize(15)
      .fontWeight(FontWeight.Medium)
      .fontColor(AppColors.TEXT_DARK)
    Blank()
    Text(`${count} 个`)
      .fontSize(13)
      .fontColor(AppColors.TEXT_GRAY)
  }
  .width('100%')
  .padding({ left: 4, right: 4, top: 8, bottom: 8 })
}

左边日期、右边条数,Blank() 撑开。ListItemGroup 的 header 参数接收一个 @Builder 调用,所以日期滚动时会跟着组走 —— 这是 ListItemGroup 相比「在列表里插一行普通 item」的主要好处。

使用天数

getDaysSince 算的是「已使用几天」:

static getDaysSince(firstDate: number): number {
  if (firstDate <= 0) {
    return 0;
  }
  const diff: number = Date.now() - firstDate;
  const oneDay: number = 24 * 60 * 60 * 1000;
  return Math.floor(diff / oneDay) + 1;
}

+1 让首次使用当天就显示「1 天」。如果按 Math.floor 的原始结果,安装当天看到的是「已使用 0 天」,读起来像没生效。

这里用的是「除以 86400000 再取整」,也就是按 24 小时切分,不是按自然日。首次使用时间如果是昨天 23:00,今天 01:00 打开,diff 是 2 小时,Math.floor 得 0,加 1 显示「1 天」—— 从日历上看已经跨了一天,但显示仍是 1。反过来,首次使用是今天 00:30,今天 23:30 打开,diff 是 23 小时,显示还是「1 天」。这个口径下「已使用 N 天」实际是「第 N 个 24 小时周期」,不是「第 N 个自然日」。

firstDate <= 0 返回 0,对应 FIRST_USE_DATE 还没写入的状态。MinePage 直接把它拼进文案:

Text(`已使用 ${GradeUtils.getDaysSince(this.firstUseDate)} 天`)
  .fontSize(15)
  .fontColor(AppColors.TEXT_GRAY)

ensureFirstUseDate 保证了这个值在进入主页面前一定已经写好:

async ensureFirstUseDate(): Promise<void> {
  const existing: number = AppStorage.get<number>(StoreKeys.FIRST_USE_DATE) ?? 0;
  if (existing <= 0) {
    const now: number = Date.now();
    await this.pref?.put(PrefKeys.FIRST_USE_DATE, now);
    await this.pref?.flush();
    AppStorage.setOrCreate(StoreKeys.FIRST_USE_DATE, now);
  }
}

只在「当前值不大于 0」时写入,所以第二次调用不会覆盖首次时间。SplashPage 与 GradeSelectPage.startLearning 都调了它,两处都可能是一次使用 —— 谁先跑谁写,后跑的读到非零值直接跳过。SplashPage 里那一处没有 await:

if (storage.hasSelectedGrade() && repo.isLoaded()) {
  storage.ensureFirstUseDate();
  await router.replaceUrl({ url: 'pages/MainPage' });
}

ensureFirstUseDate() 返回 Promise 但没 await,紧跟的 replaceUrl 不等它。这不影响正确性 —— AppStorage.setOrCreate 在 await put 之后才执行,所以跳转发生时 FIRST_USE_DATE 可能还是 0,MinePage.aboutToAppear 会读到 0 并显示「已使用 0 天」。等 put 完成、setOrCreate 触发 @StorageLink 更新,数字会跳到 1。

一处时区约定

四个时间函数全部用 Date 的本地方法:getFullYear、getMonth、getDate。没有一处用 getUTCxxx。这让所有显示都是「设备本地时间」:

函数依赖结果口径
formatTimeAgoDate.now() 差值绝对时长,与时区无关
formatDategetFullYear/getMonth/getDate本地自然日
formatDateKey同上本地自然日
getDaysSince时间戳差值24 小时周期,与时区无关

同一条记录在不同时区的设备上,formatDateKey 可能给出不同的日期 —— 这恰恰是对的,因为「我哪天学的」应该按用户所在的本地日算。getDaysSince 反过来不受时区影响,它是纯差值除法。

工具类到这里就完整了:一组年级键的正反转换,四个时间函数,全部是纯函数、全部无状态、全部只依赖入参和 Date.now()。它们被四个页面和一个数据源调用,但没有一处需要初始化 —— 这是把「格式」从「逻辑」里剥出来的直接收益。

Logo

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

更多推荐