桌面卡片(Form)是鸿蒙上很容易出彩、也很容易出问题的功能。最典型的现象是:应用里的数据明明变了,桌面上那张卡片还是昨天的。
这篇按一次真实排查的顺序走一遍。结论先放这:卡片不刷新,八成不是"刷新机制没调通",而是卡片和应用之间根本没有共享同一份数据源。
一、先明确卡片是另一个进程
这个认知是排查的起点,也是所有人第一次踩坑的原因。
桌面卡片运行在 launcher(桌面)的进程里,不在你的应用进程里。
这意味着一整串东西在卡片里都用不了:应用的 @State、AppStorage、任何内存状态、全局单例、建好的数据库连接、网络请求实例、应用里的 UI 组件。
所以"我在应用里改了 AppStorage,卡片应该跟着变"这个想法,从一开始就不成立。跨进程了,内存是分开的。
卡片能用的只有三样:LocalStorage(卡片自己的)、formProvider 的数据通道、以及持久化存储(Preferences / 关系型数据库 / 文件)。
二、刷新有四条路,先确认走的是哪条
| 方式 | 触发方 | 用途 |
|---|---|---|
| 定时刷新 | 系统 | 按 updateEnabled 配置的周期自动拉 |
| 主动刷新 | 应用 | 应用更新数据后主动推给卡片 |
| 卡片事件 | 用户 | 用户点卡片上的按钮回调 |
| 状态刷新 | 系统 | 卡片状态变化(如尺寸变化)时重绘 |
先确认一件事:你的卡片在 form_config.json 里配置了哪种。
{
"forms": [
{
"name": "weather",
"src": "./ets/widget/pages/WeatherCard.ets",
"uiSyntax": "arkts",
"updateEnabled": true,
"scheduledUpdateTime": "10:30",
"updateDuration": 1,
"defaultDimension": "2*2",
"supportDimensions": ["2*2", "4*2"]
}
]
}
三个关键字段:updateEnabled 设成 false 就只剩主动刷新一条路;updateDuration 单位是 30 分钟(写 1 表示每 30 分钟一次),这是最容易误读的地方;scheduledUpdateTime 指定时刻刷新,格式 HH:mm。
定时刷新的最小粒度就是 30 分钟,想更频繁只能主动刷新。
三、主动刷新的三层结构
主动刷新是绝大多数"实时性"需求的正解。它涉及三个角色,必须全部打通。
第一层:卡片提供方更新数据。
async function updateAllCards(context: common.UIAbilityContext) {
// 1. 先把数据落持久化,卡片醒来时能读到
await saveCardData(context, newData);
// 2. 找出所有还在桌面上的本应用卡片
const formIds = await formProvider.getFormsInfo(context);
// 实际用 getAllFormsInfo 或按 moduleName 过滤
// 3. 逐个通知刷新
for (const item of formIds) {
const want: Want = {
bundleName: context.abilityInfo.bundleName,
abilityName: 'EntryFormAbility',
parameters: {
formId: item.formId, message: 'update' }
};
await formProvider.requestForm(want);
}
}
重点不是 API 名字,是顺序:先持久化,再通知刷新。反过来的话,卡片收到刷新请求去读数据,可能读到的还是旧值——写库的异步操作还没完成。
第二层:EntryFormAbility 接收刷新请求。
export default class EntryFormAbility extends FormExtensionAbility {
async onFormEvent(formId: string, message: string) {
const latest = await readCardDataFromStorage(formId);
const data = formBindingData.createFormBindingData(latest);
await this.context.updateForm(formId, data);
}
}
updateForm 是真正把数据推给卡片渲染的调用。它必须在 FormExtensionAbility 里调用,不能在普通 UIAbility 里调。
第三层:卡片 UI 接收数据。
@Entry(storage)
@Component
struct WeatherCard {
@LocalStorageProp('temperature') temperature: string = '--';
@LocalStorageProp('city') city: string = '';
build() {
Column() {
Text(this.city).fontSize(14)
Text(this.temperature).fontSize(28).fontWeight(FontWeight.Bold)
}
}
}
卡片侧必须用 @LocalStorageProp 或 @LocalStorageLink 接数据。用 @State 接不到——@State 的初值在组件构造时求,而 updateForm 推过来的数据是构造之后才到的。
四、五个真实的不刷新原因
原因一:数据只写在应用内存里。这是最常见的一个。应用里 this.weatherData = newData,然后 requestForm,卡片醒来去读持久化——那里还是旧的。
async function saveCardData(context: common.Context, data: CardData) {
const store = await preferences.getPreferences(context, 'card_store');
await store.put('temperature', data.temperature);
await store.flush(); // ← 不 flush 不落盘
}
flush() 这一步很容易忘。put 只写内存缓存,不落盘,进程一退数据就没了。
原因二:requestForm 的 want 里 abilityName 写错。必须是 FormExtensionAbility 的名字,不是 UIAbility 的。写成 EntryAbility 会静默失败——没有报错,卡片就是不刷新。排查手段:在 onFormEvent 第一行加日志,没进来就是 want 写错了。
原因三:formId 已失效。用户把卡片从桌面删了,formId 就失效。还拿旧 formId 去 requestForm,失败但不抛异常。修法:刷新前先 getFormsInfo 拿当前有效列表,别缓存 formId;同时处理 onRemoveForm 回调清理关联数据。
原因四:卡片 UI 用了 @State 接数据。这在开发期特别隐蔽,因为预览器里用 @State 是能看到效果的(给的是初始值),只有真机推数据才暴露。判据:卡片文件里 grep @State,有就改成 @LocalStorageProp。
原因五:主动刷新被频率限制。系统对 updateForm 有频率限制,同一个卡片短时间内刷太多次会被丢弃。修法:应用侧做节流,数据变化频繁的场景(股票行情这类)攒几十秒推一次。
五、一个完整的正确链路
数据源变化(应用进程)
↓ 1. 写入持久化(Preferences.put + flush)
↓ 2. 查出当前有效 formId(getFormsInfo)
↓ 3. 逐个 requestForm(want 指向 FormExtensionAbility)
↓ 4. FormExtensionAbility.onFormEvent 被调起
↓ 5. 从持久化读出最新数据
↓ 6. formBindingData.createFormBindingData(data)
↓ 7. this.context.updateForm(formId, bindingData)
↓ 8. 卡片进程收到数据 → LocalStorage 更新 → UI 重绘
每一步都能断,所以每一步都要日志。排查顺序不是从 1 到 8,而是从中间开始二分——先确认 onFormEvent 有没有进来,进来了就是 5~8 的问题,没进来就是 1~4 的问题。
六、如果还不行,查这三处配置
第一处:module.json5 里有没有声明 FormExtensionAbility。
{
"module": {
"extensionAbilities": [
{
"name": "EntryFormAbility",
"srcEntry": "./ets/widget/EntryFormAbility.ets",
"type": "form",
"metadata": [
{ "name": "ohos.extension.form", "resource": "$profile:form_config" }
]
}
]
}
}
type 必须是 "form",metadata 里的 resource 必须指向 form_config.json。少一样就整个不生效。
第二处:form_config.json 的 src 路径。这个路径是相对于模块根目录的。写成 src/main/ets/... 会找不到。路径错了的表现是卡片添加时直接失败,不会静默。
第三处:卡片尺寸和布局对不对。如果布局只按 22 写了,用户加了 42 的卡片,内容会挤在左上角。这一条不导致"不刷新",但会让用户觉得"卡片坏了"。
七、一张排查表
| 现象 | 最可能的原因 | 查什么 |
|---|---|---|
| 完全不刷新,onFormEvent 没进来 | want 写错 / formId 失效 / 没声明 Extension | onFormEvent 加日志,看 want 的 abilityName |
| onFormEvent 进来了但数据是旧的 | 数据没落持久化 / 忘了 flush | 检查 put 之后有没有 flush() |
| 应用重启后卡片变回初始值 | 持久化没做 / key 不一致 | 对比 put 和 get 的 key |
| 有时刷新有时不刷 | 频率限制 | 应用侧加节流 |
| 预览器正常,真机不动 | 用了 @State 接数据 | grep 卡片文件的 @State |
| 卡片加不上桌面 | form_config.json 路径错 / 尺寸配置错 |
检查 src 是否相对模块根 |
八、最后一句
卡片刷新这块最大的心智负担是接受"卡片是另一个进程"。一旦接受这个前提,所有"为什么不刷新"的问题都变成同一句话:这份数据在卡片进程里能不能读到?读不到就不刷新,跟机制无关。
如果你想系统看一遍元服务和卡片这块——不同尺寸布局、卡片间数据共享、卡片跳转应用内页面,可以看看誉天教育的鸿蒙课,它第一阶段排的是 ArkTS 与开发环境、ArkUI 与状态管理、数据网络与权限、多端适配与 AI 入口四块,多端适配那一块把卡片和普通页面放在一起讲差异。