【共创稿事节】HarmonyOS7 【拼词小达人】服务卡片的类型分发与两次推送
两张卡片共用同一个 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"]
}
]
}
| 字段 | progressWidget | wordOfDayWidget | 影响 |
|---|---|---|---|
defaultDimension | 2*2 | 4*4 | 桌面上占的格子数 |
supportDimensions | 只有 2*2 | 只有 4*4 | 不支持用户拉伸手势 |
isDefault | true | false | 添加卡片时的默认选中项 |
updateEnabled | true | true | 允许定时与主动刷新 |
scheduledUpdateTime | 08:00 | 08:00 | 每天早晨刷一次 |
isDynamic | true | true | 内容可动态变化 |
colorMode | auto | auto | 声明跟随系统深浅色 |
两个条目都只支持一种尺寸。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 | 拉起指定 Ability | abilityName、params | 两张卡的点击 |
message | 回调 onFormEvent | params(任意) | 单词卡「换一个」 |
call | 拉起指定 Ability 并走 call 事件 | abilityName、method | 未使用 |
message 不拉起任何页面,只把消息交给 FormAbility.onFormEvent,所以「换一个」点下去卡片不跳转、原地换词。router 会把整个应用拉到前台,所以「开始学习」和卡片其余区域(ProgressWidgetCard 整个 Column 都挂了 onClick)都是进入应用。
两张卡片的点击区域设计不同:进度卡整卡可点,单词卡只有「开始学习」按钮可点。原因是单词卡上还有「换一个」按钮,整卡可点会让两个操作区域重叠 —— 用户想换词却进了应用。
卡片这一层的分工到这里清楚了:FormAbility 管数据构建和类型分发,两张 @ComponentV2 卡片只管画。中间的数据契约是一个扁平的 Record<string, string>,两边的键名必须对上,而这一点没有任何编译期检查 —— 键名写错只会让卡片显示默认值。
更多推荐
所有评论(0)