HarmonyOS 服务卡片:静态卡、动态卡与刷新预算

举报
yd_260750576 发表于 2026/11/11 08:32:00 2026/11/11
【摘要】 做卡片的第一件事不是画 UI,是算预算。定时刷新最小间隔 30 分钟,一天最多 48 次;主动刷新还有独立配额。算完这笔账再决定卡片长什么样,比先做设计稿再删功能省事得多。我的经验是:把卡片当"快照"

做卡片的第一件事不是画 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 订单、待办、音乐控制 中
纯点击刷新 用户触发 拉起应用 低频查询类 最低

五、自检清单

  1. 先算刷新频率,超过 48 次/天的需求改用主动刷新或降低精度。
  2. onUpdateForm 内不做网络请求,缓存优先。
  3. 主动刷新要有节流,同一 formId 一分钟内不超过一次。
  4. 每个尺寸单独做布局,文案分级。
  5. 卡片上显示最后更新时间,降低用户对陈旧数据的感知。
  6. 删除卡片时清理对应的缓存 key,否则缓存会随添加次数累积。
  7. 上线前在低端机上验证冷启动添加卡片的耗时,超过 1 秒就要查初始化逻辑。
【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。