两张卡片共用同一个 FormExtensionAbility:一张 2×2 的学习进度卡,一张 4×4 的每日单词卡。onAddForm 的返回值和 onUpdateForm 的推送是两条不同的路径 —— 前者必须同步给出首屏数据,后者可以在初始化完成后补第二次。这个「先给能给的,再补真数据」的两段式,是卡片首帧不空白的关键。

两张卡片的配置差异

form_config.json 里两个条目,除了尺寸,其余字段几乎一样:

服务卡片切图

图:两种服务卡片尺寸的实际展示效果。

{
  "forms": [
    {
      "name": "progressWidget",
      "displayName": "$string:form_progress_name",
      "description": "$string:form_progress_desc",
      "src": "./ets/widget/pages/ProgressWidgetCard.ets",
      "uiSyntax": "arkts",
      "isDefault": true,
      "updateEnabled": true,
      "scheduledUpdateTime": "08:00",
      "defaultDimension": "2*2",
      "supportDimensions": ["2*2"],
      "isDynamic": true,
      "colorMode": "auto",
      "previewImages": ["$media:progressWidget_2x2"]
    },
    {
      "name": "wordOfDayWidget",
      "displayName": "$string:form_word_name",
      "description": "$string:form_word_desc",
      "src": "./ets/widget/pages/WordOfDayWidgetCard.ets",
      "uiSyntax": "arkts",
      "isDefault": false,
      "updateEnabled": true,
      "scheduledUpdateTime": "08:00",
      "defaultDimension": "4*4",
      "supportDimensions": ["4*4"],
      "isDynamic": true,
      "colorMode": "auto",
      "previewImages": ["$media:wordOfDayWidget_4x4"]
    }
  ]
}
字段progressWidgetwordOfDayWidget影响
defaultDimension2*24*4桌面上占的格子数
supportDimensions只有 2*2只有 4*4不支持用户拉伸手势
isDefaulttruefalse添加卡片时的默认选中项
updateEnabledtruetrue允许定时与主动刷新
scheduledUpdateTime08:0008:00每天早晨刷一次
isDynamictruetrue内容可动态变化
colorModeautoauto声明跟随系统深浅色

两个条目都只支持一种尺寸。supportDimensions 是单元素数组,意味着卡片在桌面上不能被拉成 2*4 或 4*2 —— 一旦支持多尺寸,build 里就得分情况布局,而这两张卡的排版对宽高比很敏感(4×4 的单词卡靠三处 Blank() 撑开纵向节奏)。

colorMode: "auto" 声明了跟随系统主题,但两个卡片 .ets 里的颜色全是硬编码:

.linearGradient({
  angle: 180,
  colors: [['#F7FFF7', 0], ['#E3F8F4', 1]]
})

#F7FFF7 与 #E3F8F4 都是浅色,正文用 #2D3436 与 #636E72。也就是说深色主题下卡片仍然是一块浅色面板,auto 只是声明,没有对应的适配代码(比如按 @StorageProp('colorMode') 取两套配色)。这在桌面上一眼能看出来,但它是「卡片保持品牌浅绿」这个视觉决定的副产品,不是遗漏。

onAddForm 的两段返回

onAddForm 的签名要求同步返回一个 FormBindingData,这是整件事的约束来源:

onAddForm(want: Want) {
  const params = want.parameters;
  let formId: string = '';
  let formName: string = '';

  if (params) {
    const formIdObj = params['ohos.extra.param.key.form_identity'];
    const formNameObj = params['ohos.extra.param.key.form_name'];
    if (formIdObj) {
      formId = `${formIdObj}`;
    }
    if (formNameObj) {
      formName = `${formNameObj}`;
    }
  }

  if (formId.length > 0) {
    this.formMap.set(formId, formName);
  }

  // 异步初始化数据,不阻塞onAddForm返回
  this.initData().then(() => {
    if (formId.length > 0) {
      this.refreshForm(formId, formName);
    }
  }).catch((e: Error) => {
    console.error('FormAbility init error:', JSON.stringify(e));
  });

  if (formName === 'wordOfDayWidget') {
    return formBindingData.createFormBindingData(this.buildWordOfDayData());
  } else {
    return formBindingData.createFormBindingData(this.buildProgressData());
  }
}

四件事按顺序发生:

顺序动作是否阻塞返回
1从 want.parameters 取 form_identity 与 form_name是(同步)
2把 formId → formName 记进 formMap是(同步)
3发起 initData(),完成后调 refreshForm否(.then 挂上去就返回)
4按 formName 构建数据并 return是(同步)

两个参数名是固定的字符串常量:

ohos.extra.param.key.form_identity
ohos.extra.param.key.form_name

params 的类型是 Record<string, Object>,取值出来是 Object,所以用 `${formIdObj}` 转成字符串而不是 as string。模板字符串对任何值都成立:undefined 会变成字符串 'undefined',所以外面必须套 if (formIdObj)。

formName 同时承担两个角色:formMap 的值,以及分发判断的依据。判断写成 if (formName === 'wordOfDayWidget') { ... } else { ... },把进度卡放在 else 分支 —— 名字对不上、参数缺失、formName 是空串,全部落到进度卡。这个默认值的选择是有意的:进度卡只读三个计数,数据缺失时显示 0,是一张「看起来正常」的卡片;单词卡在数据缺失时会显示硬编码的 Welcome,用户一眼能看出不对劲。

同步返回时数据是什么

buildProgressData 在第一次被调用时,StorageService 可能还没初始化:

private buildProgressData(): Record<string, string> {
  const storage = StorageService.getInstance();
  const learned: number = storage.getLearnedCount();
  const mastered: number = storage.getMasteredTotal();
  const collected: number = storage.getCollectedTotal();
  const gradeName: string = AppStorage.get<string>('selectedGradeName') ?? '未选择年级';

  const today = new Date();
  const dateStr = `${today.getMonth() + 1}月${today.getDate()}日`;

  return {
    'gradeName': gradeName,
    'learnedCount': `${learned}`,
    'masteredCount': `${mastered}`,
    'collectedCount': `${collected}`,
    'dateStr': dateStr
  };
}

getLearnedCount() 遍历 statsMap,Map 是空的,返回 0;AppStorage.get('selectedGradeName') 在 init 之前是 undefined,?? 兜成「未选择年级」。所以首次 onAddForm 返回的是一张「未选择年级 / 0 / 0 / 0」的卡 —— 除了日期是对的,其余全是占位值。

这正是 initData().then(refreshForm) 存在的理由。initData 把两个单例补齐:

private async initData(): Promise<void> {
  if (!StorageService.getInstance().isInitialized()) {
    await StorageService.getInstance().init(this.context);
  }
  if (!WordRepository.getInstance().isLoaded()) {
    await WordRepository.getInstance().load(this.context);
  }
}

this.context 在 FormExtensionAbility 里是扩展自己的 Context,preferences.getPreferences(this.context, 'en_ordmester') 与主应用读的是同一张表 —— 表是按应用沙箱存的,不区分入口。所以卡片进程能读到用户在应用里选过的年级和学过的词。

两个 if 是必须的。桌面刷新、用户重进、进程被回收后重建,各种时机下这两个单例的状态不确定;不加判断就会重复 init,StorageService.init 里没有幂等保护(WordRepository.load 里有)。

refreshForm 是第二段推送:

private refreshForm(formId: string, formName: string): void {
  if (formName === 'wordOfDayWidget') {
    formProvider.updateForm(formId, formBindingData.createFormBindingData(this.buildWordOfDayData()));
  } else {
    formProvider.updateForm(formId, formBindingData.createFormBindingData(this.buildProgressData()));
  }
}

它和 onAddForm 末尾的分发逻辑几乎一样,区别只在「返回值」和「updateForm 调用」。这段重复可以合并(让 buildXxxData 之外再抽一个 buildDataFor(name)),当前写法把两条路径摊开写,读起来不需要跳转。

两段之间的时间差取决于 initData 的耗时:preferences 打开、四个键读取、statsMap 反序列化、950KB 词库解码建表。单词卡必须在第二段之后才有真实单词,进度卡在第二段之后才有真实计数。用户看到的是卡片先出现(占位值),零点几秒后数字跳一下。

对进度卡来说,这个「跳」不理想但可接受 —— 从 0 变成 12 比空白好。对单词卡来说,第一段显示的 Welcome 会闪一下再变成真词,视觉上是个明显切换。要让两段之间不闪,只能在第一段直接返回空数据、让卡片自己显示骨架,但那样首帧就是一片空白,反而更差。

三种刷新入口的分发

卡片有四个生命周期回调,三个都要按类型分发:

onUpdateForm(formId: string) {
  // 根据保存的卡片类型分发刷新
  const formName: string | undefined = this.formMap.get(formId);
  if (formName === 'wordOfDayWidget') {
    // 每日定时刷新时轮换新单词
    formProvider.updateForm(formId, formBindingData.createFormBindingData(this.buildWordOfDayData()));
  } else {
    formProvider.updateForm(formId, formBindingData.createFormBindingData(this.buildProgressData()));
  }
}

onRemoveForm(formId: string) {
  this.formMap.delete(formId);
}

onFormEvent(formId: string, message: string) {
  console.info(`FormAbility onFormEvent: ${formId}, msg: ${message}`);
  // 用户点击"换一个"按钮时刷新单词卡片
  const formName: string | undefined = this.formMap.get(formId);
  if (formName === 'wordOfDayWidget') {
    formProvider.updateForm(formId, formBindingData.createFormBindingData(this.buildWordOfDayData()));
  }
}

三条路径的共同点是都先查 formMap:

回调触发者查不到 formName 时
onUpdateForm每日 08:00 定时、系统主动刷新走 else,推进度卡数据
onFormEvent卡片内 postCardAction 的 message什么都不做(整个 if 不进入)
onRemoveForm用户从桌面删卡直接删一个不存在的键

onUpdateForm 的 else 兜底和 onAddForm 一致;onFormEvent 没有 else,因为它的语义是「某张卡发来一个消息」,类型不明时无法决定推什么数据,宁可不动。

formMap 是 FormExtensionAbility 的实例成员:

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

它只活在内存里,不落盘。卡片扩展进程被系统回收后重新拉起,formMap 是空的,此时来的 onUpdateForm 查不到类型,会推一份进度卡数据给一张单词卡。结果是 4×4 的版面上出现三个统计数字 —— 布局是 wordText 那些键对应的模板,缺数据时全部显示默认值(Welcome / /ˈwelkəm/)。

要彻底避免,得把类型信息存进 formBindingData 的结构里、或者用 formProvider 的持久化能力按 formId 记一份。当前实现接受了这个窗口,因为被回收后重新拉起的场景本身不频繁,且下次用户点开应用时 onUpdateForm 会拿到正确数据。

onFormEvent 里 message 参数只被打进日志,没有参与判断:

console.info(`FormAbility onFormEvent: ${formId}, msg: ${message}`);

卡片侧发的消息长这样:

postCardAction(this, {
  action: 'message',
  params: { 'method': 'refresh' }
});

method: 'refresh' 这个字段服务端从来没读。目前只有「换一个」一个消息来源,所以「收到消息就刷新」等价于「收到换一个就刷新」。等哪天加了「收藏这个词」这类按钮,就必须解析 message 里的 method 才能区分 —— 现在这行日志是唯一的线索。

卡片侧的两种跳转

两张卡片都用了 postCardAction,但 action 不同:

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

action: 'router' 拉起 EntryAbility,params 是空的 —— 卡片不告诉应用「用户是从哪张卡点进来的」。应用侧 EntryAbility.onCreate 也没读 want,onWindowStageCreate 一律 loadContent('pages/SplashPage'),然后由 SplashPage 按「有没有选过年级」分流。所以从进度卡点和从桌面图标点,走的是同一条路。要做到「点单词卡直接进学习页」,得把目标页塞进 params,再在 SplashPage 里读 want 参数 —— 现在没有这条链路。

三种 action 的分工:

action目标需要的参数本项目的用法
router拉起指定 AbilityabilityName、params两张卡的点击
message回调 onFormEventparams(任意)单词卡「换一个」
call拉起指定 Ability 并走 call 事件abilityName、method未使用

message 不拉起任何页面,只把消息交给 FormAbility.onFormEvent,所以「换一个」点下去卡片不跳转、原地换词。router 会把整个应用拉到前台,所以「开始学习」和卡片其余区域(ProgressWidgetCard 整个 Column 都挂了 onClick)都是进入应用。

两张卡片的点击区域设计不同:进度卡整卡可点,单词卡只有「开始学习」按钮可点。原因是单词卡上还有「换一个」按钮,整卡可点会让两个操作区域重叠 —— 用户想换词却进了应用。

卡片这一层的分工到这里清楚了:FormAbility 管数据构建和类型分发,两张 @ComponentV2 卡片只管画。中间的数据契约是一个扁平的 Record<string, string>,两边的键名必须对上,而这一点没有任何编译期检查 —— 键名写错只会让卡片显示默认值。

Logo

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

更多推荐