HarmonyOS 服务卡片:静态卡、动态卡与刷新预算
做卡片的第一件事不是画 UI,是算预算。定时刷新最小间隔 30 分钟,一天最多 48 次;主动刷新还有独立配额。算完这笔账再决定卡片长什么样,比先做设计稿再删功能省事得多。我的经验是:把卡片当"快照"而不是"缩小的应用"。
一、先把预算算清楚:48 次是上限,不是目标
updateDuration 的单位是 30 分钟,最小值也是 30。这意味着纯定时刷新的卡片,一天最多被系统唤醒 48 次。这个数字听起来不少,但摊到"股票行情"这种场景就不够用了——集合竞价那几分钟,48 次配额连一个小时都撑不住。
所以卡片的刷新策略必须分层。第一层是定时刷新,负责保底,让用户在任何时候打开都能看到不超过 30 分钟的旧数据。第二层是主动刷新,在用户真正关心的时刻调用 formProvider.updateForm,比如支付完成、订单状态变更。第三层是点击刷新,用户点一下卡片,拉起应用的瞬间顺手更新。
第三层的成本最低但体验最差,因为用户已经先看到了旧数据。我的做法是把"最后更新时间"直接画在卡片角落,用相对时间(3 分钟前)代替绝对时间,用户对陈旧度的容忍度会明显提高。
二、静态卡不是"不能动",是"不值得动"
静态卡片(配置里 isDynamic 置 false)在渲染完成后不参与常规刷新流程,也不支持卡片内的交互事件回传。它的优势是启动快、内存占用低,适合"信息展示型"场景:日程、天气、步数、快递进度。
动态卡片支持 postCardAction 的三种动作:router 拉起指定页面、call 拉起 Ability、message 把消息回传给 FormExtensionAbility。需要按钮、需要局部刷新、需要根据用户操作改变内容的,只能选动态卡片。
选型上我有个粗暴的判断:如果卡片上除了"点一下打开应用"之外没有别的交互,就用静态卡。多一个按钮,就得多一套事件处理和状态同步,收益往往抵不过复杂度。
三、onUpdateForm 里不要发网络请求
这是我最想强调的一条。onUpdateForm 有执行时间限制,超时会被系统判定失败,卡片停留在旧数据。而卡片的刷新往往发生在设备刚唤醒、网络还没稳定的时刻,请求失败率比前台高得多。
正确做法是"缓存优先 + 异步补":回调里先用本地缓存渲染,保证这次刷新一定成功;同时发起请求,拿到新数据后通过 updateForm 再刷一次。
// src/main/resources/base/profile/form_config.json
{
"forms": [
{
"name": "order_card",
"description": "$string:order_card_desc",
"src": "./ets/ordercard/pages/OrderCard.ets",
"uiSyntax": "arkts",
"isDefault": true,
"colorMode": "auto",
"supportDimensions": ["2*2", "4*4"],
"defaultDimension": "2*2",
"updateEnabled": true,
"updateDuration": 30,
"scheduledUpdateTime": "08:30"
}
]
}
updateDuration 和 scheduledUpdateTime 同时配置时,系统会按两者计算触发点。我一般只在需要"每天固定时刻对齐"的场景下配后者,比如早八点半的日程卡,其余场景只配 updateDuration,减少不可预期的唤醒。
import { FormExtensionAbility, formBindingData, formProvider } from '@kit.FormKit';
import { Want } from '@kit.AbilityKit';
export default class OrderCardAbility extends FormExtensionAbility {
onAddForm(want: Want): formBindingData.FormBindingData {
// 首次添加:直接用缓存,不阻塞
return formBindingData.createFormBindingData({ count: '0', latest: '暂无订单' });
}
onUpdateForm(formId: string): void {
const cached = CardCache.read(formId); // 同步读本地缓存,毫秒级
if (cached) {
formProvider.updateForm(formId, formBindingData.createFormBindingData(cached));
}
// 网络请求放到异步任务里,拿到结果再刷一次,失败不影响本次刷新
void refreshFromServer(formId);
}
}
这段代码的关键是"两次 updateForm":第一次保证有内容,第二次保证内容新。只写第二次的实现,在网络差的时候会看到卡片空白或长时间不更新。
四、尺寸是两套设计,不是一套设计缩放
2*2 和 4*4 不是同一张图放大。2*2 的安全区大约只有 2 行文本加一个数字,4*4 能放列表。如果只做一套布局,在小尺寸上一定溢出,在大尺寸上一定空旷。
我的做法是给每个尺寸单独写一个 build 分支,通过 FormComponent 的尺寸参数或者页面入参判断。文案也要分尺寸准备:2*2 只放结论(“3 个待收货”),4*4 才放明细(具体订单号和时间)。
| 类型 | 刷新方式 | 交互能力 | 典型场景 | 成本 |
|---|---|---|---|---|
| 静态卡 | 定时 + 主动,不支持事件回传 | 仅点击拉起 | 天气、步数、日程 | 低 |
| 动态卡 | 定时 + 主动 + 事件触发 | router/call/message | 订单、待办、音乐控制 | 中 |
| 纯点击刷新 | 用户触发 | 拉起应用 | 低频查询类 | 最低 |
五、自检清单
- 先算刷新频率,超过 48 次/天的需求改用主动刷新或降低精度。
onUpdateForm内不做网络请求,缓存优先。- 主动刷新要有节流,同一 formId 一分钟内不超过一次。
- 每个尺寸单独做布局,文案分级。
- 卡片上显示最后更新时间,降低用户对陈旧数据的感知。
- 删除卡片时清理对应的缓存 key,否则缓存会随添加次数累积。
- 上线前在低端机上验证冷启动添加卡片的耗时,超过 1 秒就要查初始化逻辑。
- 点赞
- 收藏
- 关注作者
评论(0)