桌面卡片只有两种尺寸,2×2 和 4×4,相差四倍的面积。这个差距不能靠同一套布局缩放解决 —— 2×2 上放不下一个 36 号字的大单词,4×4 上放三个统计数字又太空。项目为此写了两份完全独立的 ArkUI 声明,连颜色都是从零硬编码的,而取词逻辑只关心一件事:下一次刷新该给第几个词。

两份独立的声明

两个卡片文件都以 @ComponentV2 开头:

@Entry
@ComponentV2
struct ProgressWidgetCard {
  @Local gradeName: string = '未选择年级';
  @Local learnedCount: string = '0';
  @Local masteredCount: string = '0';
  @Local collectedCount: string = '0';
  @Local dateStr: string = '';
@Entry
@ComponentV2
struct WordOfDayWidgetCard {
  @Local wordText: string = 'Welcome';
  @Local phonetic: string = '/ˈwelkəm/';
  @Local meaning: string = '欢迎';
  @Local category: string = '基础词汇';
  @Local unitTopic: string = '开始学习';

五个 @Local 对应 formBindingData 里的五个键,键名完全一致。@ComponentV2 与主应用的 @Component 是两套状态管理:卡片侧用 @Local,主应用侧用 @State / @Prop / @StorageLink。选 V2 的原因是卡片只需要「接收绑定数据并显示」,没有任何 @Prop 传递、没有跨组件同步,V2 的 @Local 语义更贴近这个场景 —— 它就是「这个组件自己的可变状态」。

所有字段的初值都是 Welcome / 0 这类占位值。这些初值在真机上几乎看不到,因为 formBindingData 一到位就会覆盖,但它们决定了「数据键名对不上时卡片长什么样」:wordText 拼错成 wordtext,卡片就永远停在 Welcome。初值的作用相当于一个可视化的错误提示。

2×2 的三列统计

进度卡是纵向四段:标题栏、年级、三列数字、底部提示。

Column() {
  // 顶部:应用标题区域
  Row() {
    Image($r('app.media.ic_book_learn'))
      .width(16)
      .height(16)
      .margin({ right: 6 })
    Text('拼词小达人')
      .fontSize(14)
      .fontWeight(FontWeight.Bold)
      .fontColor('#2D3436')
      .layoutWeight(1)

    Text(this.dateStr)
      .fontSize(10)
      .fontColor('#636E72')
  }
  .width('100%')
  .padding({ left: 12, right: 12, top: 10 })

  // 年级信息
  Text(this.gradeName)
    .fontSize(11)
    .fontColor('#4ECDC4')
    .fontWeight(FontWeight.Medium)
    .margin({ top: 2 })
    .width('100%')
    .padding({ left: 12 })
    .textAlign(TextAlign.Start)

标题栏用 layoutWeight(1) 把「拼词小达人」撑开,日期被推到最右侧。年级行单独占一行,padding 只给左边 12 —— 与标题栏的左右各 12 对齐,但右侧不需要,因为文本左对齐。

三列数字是全卡的核心,结构完全对称:

Row() {
  // 已学
  Column() {
    Image($r('app.media.ic_book_word'))
      .width(18)
      .height(18)
      .margin({ bottom: 2 })
    Text(this.learnedCount)
      .fontSize(20)
      .fontWeight(FontWeight.Bold)
      .fontColor('#4ECDC4')
    Text('已学')
      .fontSize(10)
      .fontColor('#636E72')
      .margin({ top: 2 })
  }
  .layoutWeight(1)
  .alignItems(HorizontalAlign.Center)
  // 已掌握 / 收藏 同构
}
.width('100%')
.padding({ left: 12, right: 12, top: 10, bottom: 8 })

三个 Column 各拿 layoutWeight(1),宽度均分。每个内部是「图标 → 数字 → 标签」的竖排,数字用 20 号加粗、标签 10 号灰色。三列的颜色分别是 #4ECDC4(青绿)、#FF6B9D(粉)、#45B7D1(蓝),与主应用 AppColors 里的 MINT_GREEN / SOFT_PINK / SKY_BLUE 数值相同。

同一组颜色值在两处各写一份,是卡片不能 import 主应用常量的结果 —— widget/pages/*.ets 是独立的构建入口,form_config.json 用 src 直接指过去,它跑在自己的渲染树里。技术上可以 import ../common/Constants,但那样会把 Constants 打进卡片包,而卡片包里真正用到的只有 6 个色值。这里选了复制。

数字的字号是 20,比标题的 14 还大 —— 这是 2×2 空间下的必然选择:统计数字是这张卡唯一的信息量,字号必须压过装饰元素。

底部提示用 Blank() 顶到底:

Blank()

Row() {
  Text('点击打开开始学习')
    .fontSize(10)
    .fontColor('#999999')
  Image($r('app.media.ic_arrow_right'))
    .width(10)
    .height(10)
    .margin({ left: 2 })
}
.margin({ bottom: 8 })

整卡挂了 onClick 拉起应用:

.onClick(() => {
  postCardAction(this, {
    action: 'router',
    abilityName: 'EntryAbility',
    params: {}
  });
})

所以底部这行「点击打开开始学习」不是按钮,是提示 —— 点它和点空白处效果一样。

4×4 的单卡主体

单词卡竖排五段:标题栏、提示语、白色卡片、底部按钮、渐变底。

白色卡片是唯一有阴影的容器:

服务卡片切图

图:服务卡片在不同版面密度下的实际效果。

Column() {
  // 大单词
  Text(this.wordText)
    .fontSize(36)
    .fontWeight(FontWeight.Bold)
    .fontColor('#2D3436')

  // 音标
  Text(this.phonetic)
    .fontSize(14)
    .fontColor('#4ECDC4')
    .margin({ top: 6 })

  // 分类标签
  Row() {
    Text(this.category)
      .fontSize(10)
      .fontColor('#4ECDC4')
      .backgroundColor('#E0F7F5')
      .borderRadius(10)
      .padding({ left: 8, right: 8, top: 3, bottom: 3 })
  }
  .margin({ top: 10 })

  // 释义
  Text(this.meaning)
    .fontSize(18)
    .fontWeight(FontWeight.Medium)
    .fontColor('#636E72')
    .margin({ top: 12 })
    .textAlign(TextAlign.Center)
}
.width('85%')
.padding({ top: 20, bottom: 20 })
.backgroundColor('#FFFFFF')
.borderRadius(20)
.shadow({
  radius: 8,
  color: '#1A000000',
  offsetX: 0,
  offsetY: 2
})

width('85%') 让白卡从外层渐变底上「浮」起来,左右各留 7.5% 的底。阴影用 #1A000000 —— 前两位 1A 是 alpha(约 10%),后六位是纯黑,radius: 8 配 offsetY: 2 是一个很轻的下投影,只负责把白卡从浅绿底上分离出来,不制造「浮起」的错觉。

四个文本元素的纵向间距靠 margin({ top: n }) 逐个指定:音标 6、标签 10、释义 12。没有用 space 参数(Column({ space: n }) 只能统一间距),因为四个元素的亲密程度不同 —— 单词和音标是一组(6),音标和标签是一组(10),标签和释义再松一点(12)。

字号梯度与 2×2 的对比:

元素2×2 字号4×4 字号说明
应用名14 粗体13 粗体4×4 上应用名退居次要
日期 / 单元话题1010同类辅助信息
主数字 / 主单词20 粗体 ×336 粗体 ×1面积翻倍后集中到单个元素
音标无14只在 4×4 出现
分类标签无10只在 4×4 出现
释义无18 中等只在 4×4 出现
底部提示 / 按钮10124×4 的按钮更像按钮

两张卡的信息密度差得很远:2×2 显示 3 个数字 + 1 个年级,4×4 显示 1 个单词 + 音标 + 分类 + 释义 + 单元话题,共 5 项。2×2 的三个数字各占约三分之一宽度,4×4 的单个单词独占 85% 白卡的整行宽度。

取词的三级兜底

buildWordOfDayData 是卡片侧唯一的「业务逻辑」,它要在一个没有页面、没有用户输入的环境里挑出一个词:

private buildWordOfDayData(): Record<string, string> {
  const storage = StorageService.getInstance();
  const repo = WordRepository.getInstance();

  // 获取当前年级的所有单词
  const versionCode: string = AppStorage.get<string>('selectedVersionCode') ?? '';
  const gradeKey: string = AppStorage.get<string>('selectedGradeKey') ?? '';

  let allWords: WordInfo[] = [];
  if (versionCode.length > 0 && gradeKey.length > 0) {
    const units = repo.getUnits(versionCode, gradeKey);
    for (const unit of units) {
      allWords = allWords.concat(unit.words);
    }
  }

第一级是「当前年级的全部单词」。getUnits 返回该年级的 UnitInfo[],逐个 concat 拼成一个大数组。concat 每次都新建数组,pep 四年级上册有 6 个单元、262 个词,这轮拼接会造 6 个中间数组。换成 push(...unit.words) 能省掉这些拷贝,但 concat 的写法读起来更直接。

第二级在候选为空时启动:

  // 如果没有加载到单词,从历史记录反推
  if (allWords.length === 0) {
    const history: HistoryEntry[] = storage.getHistory();
    for (const h of history) {
      const w = repo.getWordById(h.wordId);
      if (w) {
        allWords.push(w);
      }
    }
  }

allWords 为空有两种原因:AppStorage 里的 versionCode / gradeKey 是空的(用户没选过年级),或者选了但该年级下没有词。两种情况都退到历史记录 —— 用户学过哪些词,storage.getHistory() 里有最多 200 条,逐条 getWordById 换成词对象。

这条兜底路径有个隐含前提:历史记录里的 wordId 在当前词库里能找到。切教材版本后,旧版本的词 id 仍然在 allWords 表里(四份词库同时加载),所以能找到;如果词库本身被换掉,getWordById 返回 undefined,if (w) 会跳过。

第三级是硬编码:

  let word: WordInfo | undefined;
  if (allWords.length > 0) {
    // 轮换取词
    this.wordIndex = (this.wordIndex + 1) % allWords.length;
    word = allWords[this.wordIndex];
  }

  if (!word) {
    return {
      'wordText': 'Welcome',
      'phonetic': '/ˈwelkəm/',
      'meaning': '欢迎',
      'category': '基础词汇',
      'unitTopic': '开始学习'
    };
  }

  return {
    'wordText': word.text,
    'phonetic': word.phonetic || '/--/',
    'meaning': word.meaning,
    'category': word.category,
    'unitTopic': word.unitTopic
  };
}

三级兜底的结果覆盖了从「完全没数据」到「数据完备」的全部情况:

场景第一级第二级第三级卡片显示
选过年级,有词命中 262 词不执行取一个真词
选过年级,单元全空0 词历史反推取一个历史里的词
没选年级,有历史0 词历史反推取一个历史里的词
全新安装0 词0 词命中Welcome / 欢迎

轮换是怎么步进的

this.wordIndex = (this.wordIndex + 1) % allWords.length 先自增再取模。wordIndex 初值是 0,所以第一次进这个方法取到的是下标 1,不是 0 —— 数组第一个词永远不会被选中,除非数组只有一个元素(1 % 1 = 0)。

把自增写在取值之前,好处是「同一个词不会被连续推两次」,代价是漏掉第一个。改成后置(先取 allWords[this.wordIndex] 再自增)能拿到第一个词,但连续两次调用的第二次会和第一次不同 —— 两种写法各有取舍,这里选了不需要额外判断的那种。

步进的触发点只有两个:onAddForm 里的第二次 refreshForm,和 onUpdateForm(每日 08:00 由系统触发)。按 scheduledUpdateTime: "08:00" 的设计意图,用户每天早上会看到一个新词,一天推进一格,262 个词走完一轮要 262 天。

实际的步进节奏受实例生命周期影响。wordIndex 是 FormAbility 的实例字段:

export default class FormAbility extends FormExtensionAbility {
  private formMap: Map<string, string> = new Map<string, string>();
  private wordIndex: number = 0;

卡片扩展进程被回收后重新拉起,wordIndex 回到 0,下一次刷新又从下标 1 开始。所以「一天一格」只在进程长期存活时成立;进程重启过,就会看到「又跳回前面某个词」。

如果要做严格的「每日一词」,得把日期算进去 —— 比如用「自首次使用以来的天数」对词数取模:

const days: number = GradeUtils.getDaysSince(firstUseDate);
const index: number = days % allWords.length;

这样同一天内不论刷新几次、进程重启几次,取到的都是同一个词,跨天才会变。当前的「每次刷新推进一格」更像是「换一个」,与 onFormEvent 里那个手动换词按钮的语义一致 —— 两者都会推进 wordIndex,区别只在触发者。

数据契约的键名

FormAbility 返回的 Record<string, string> 和卡片里的 @Local 之间靠键名对应,没有任何类型检查:

卡片键值来源
ProgressWidgetCardgradeNameAppStorage 的 selectedGradeName,缺失为「未选择年级」
learnedCountgetLearnedCount() 转字符串
masteredCountgetMasteredTotal() 转字符串
collectedCountgetCollectedTotal() 转字符串
dateStr${month}月${day}日
WordOfDayWidgetCardwordTextword.text
phoneticword.phonetic,空则 /--/
meaningword.meaning
categoryword.category(解析时已兜底为「单词」)
unitTopicword.unitTopic

十个键全部是字符串。计数用 ${learned} 转成字符串而不是传数字,是因为 createFormBindingData 的对象值可以混合类型,但卡片侧统一用 string 更省事 —— 数值型在 ArkTS 卡片里要额外处理格式化,而这三个数字不需要任何格式化。

category 与 unitTopic 两个键在 4×4 卡片里出现的位置很近(分类标签在中间,单元话题在标题栏右侧),但它们的值来自不同层级:category 是词条自己的字段(88.5% 是「单词」),unitTopic 是单元级的话题(如「文具与书包」)。同一个词在同一个单元里,unitTopic 恒定而 category 可能每词不同。

unitTopic 在卡片上被裁剪到极小:fontSize(10),配一个 12×12 的书本图标,放在标题栏右端。这个位置本来可以放日期(像进度卡那样),但单词卡选了单元话题 —— 它比日期更有信息量,能告诉用户这个词属于哪个主题。

版面这一层的东西看起来琐碎,但它决定了卡片在桌面上「一眼能不能读懂」。2×2 靠三个大数字,4×4 靠一个大单词加四行辅助信息,两种密度对应两种阅读距离:瞥一眼看数字,多看一眼读单词。取词逻辑反过来服务版面 —— 三级兜底的目标不是「逻辑完备」,而是「任何时候卡片上都有一个像样的词可显示」。

Logo

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

更多推荐