桌面卡片(Form)不刷新这件事,绝大多数情况不是 "刷新机制没生效",而是卡片进程和应用主进程根本没有拿到同一份数据。卡片跑在 FormExtensionAbility 里,是一个独立进程,界面由系统的卡片渲染服务统一绘制、由桌面负责呈现;应用主进程改了内存里的变量,卡片进程根本看不见,它醒来时只会去读持久化存储,读到的还是旧值。所以正确的心智模型是 "数据先落盘、再推给卡片",而不是 "改完变量卡片就自己变"。官方文档还有几条容易忽略的硬限制:updateEnabled 默认是 false,元服务卡片默认就关闭自动刷新;updateDuration 的单位是 30 分钟、填 0 等于关闭;updateDuration 和 scheduledUpdateTime 同时配时定时刷新优先,定点刷新必须把 updateDuration 设成 0 才会生效;每张卡片每天通过定时方式触发刷新最多 50 次、0 点重置;setFormNextRefreshTime 的下次刷新最短 5 分钟;卡片不可见时系统只记录刷新动作和数据,等可见了再统一刷新布局 —— 这一条最容易被误判成 "罢工"。
一、先把六种刷新方式和各自的限制摆清楚
| 刷新方式 | 配置或接口 | 生效条件与限制 |
|---|---|---|
| 定时刷新 | form_config.json 的 updateDuration | 单位 30 分钟,填 N 表示 30×N 分钟;填 0 表示不生效;需 updateEnabled: true |
| 单定点刷新 | scheduledUpdateTime,"10:30" | 24 小时制精确到分;与 updateDuration > 0 同配时不生效 |
| 多定点刷新 | multiScheduledUpdateTime,"11:30,16:30" | API 18 起支持,最多 24 个时间点;与单定点同配时多定点生效 |
| 下次刷新 | setFormNextRefreshTime() | 最短 5 分钟;适合 "事件驱动" 的临时刷新 |
| 代理刷新 | dataProxyEnabled: true | API 12 起;开启后定时刷新和下次刷新不生效,但不影响定点;API 26.0.0 起可与定时 / 下次刷新共存 |
| 条件刷新 | conditionUpdate: ["network"] | API 18 可配置、26.0.0 生效;只在 "无网→有网" 时触发,网络间切换不触发;无网判定要连续断开 10 分钟 |
三个数字要记住:30 分钟是最小定时粒度、50 次 / 天是配额上限、5 分钟是下次刷新下限。有人配 updateDuration: 1(即 30 分钟一次),一天理论触发 48 次,已经几乎贴着 50 次的配额线,再叠加几次 setFormNextRefreshTime 就会撞顶,表现就是 "下午开始怎么都不刷了",第二天 0 点又自己好了。
二、机制层最容易踩的三个坑
- 优先级配错。想用定点刷新却把 updateDuration 写成 2,定点刷新直接被忽略;反过来配了 updateDuration: 1 又抱怨 "每天 10:30 没刷新",这是同一件事的两面。
- 首次刷新有最多 30 分钟偏差。卡片框架用同一个计时器轮询,第一张卡片 3:20 添加、第二张 3:40 添加,计时器 3:50 触发事件时只有第一张刷了,第二张要等到 4:20。所以 "刚加完卡片不刷新" 是设计行为,不是 bug。
- 不可见就不刷新布局。桌面滑动到别的页面、卡片被遮挡时,系统只记录刷新动作和数据,等卡片回到可见状态才统一刷布局。如果你在后台盯着日志判断 "没刷新",很容易误判。
三、五个真实的不刷新原因(按出现频率排)
| 现象 | 根因 | 怎么验证 | 修法 |
|---|---|---|---|
| 应用里数据变了,卡片还是旧的 | 数据只写进应用内存,没落持久化;preferences.put() 后忘了 flush() | 杀掉应用重进,看卡片是否变回初始值 | put 之后必须 flush(),key 与卡片侧读取严格一致 |
| 卡片完全不刷新,日志里有 onFormEvent 但没内容 | requestForm 的 want 里 abilityName 写成了 UIAbility 名(如 EntryAbility) | 在 onFormEvent 第一行打日志,没进来就是 want 错了 | 改成 FormExtensionAbility 的名字,如 EntryFormAbility |
| 偶尔刷、偶尔不刷,删了卡片再加就好了 | formId 已失效(卡片被用户删除),仍用旧 formId 调 updateForm | updateForm 返回 16501001 | 刷新前用 getFormsInfo 取当前有效列表,别长期缓存 formId;在 onRemoveForm 里清理关联数据 |
| 预览器里正常,真机推数据不动 | 卡片 UI 用 @State 接数据,只吃初始值 | 在卡片文件里 grep @State | 改成 @LocalStorageProp,配 LocalStorage 接收 onAddForm 的数据 |
| 短时间连续刷新,后几次被丢掉 | updateForm 有频率限制 | 观察是否集中在高频推送时段 | 应用侧做节流,行情类场景攒几十秒推一次 |
另外还有官方 FAQ 里四个高频场景,经常和上面五条混在一起:
- 设备重启前后数据不一致。卡片框架重启时用的是 onAddForm() 的返回值,如果你重启前用 updateForm() 推过新数据,两边就会对不上。正确做法是在 onAddForm() 里读数据库 / 首选项的最新值,再调一次 updateForm()。
- 日志出现 Cannot get SourceMap info, dump raw stack。通常是有 API 写法错误,或卡片页面直接 / 间接引入了不支持卡片的模块。典型例子:http.createHttp() 只有 @atomicservice 标签、没有 @form 标签,就属于卡片不支持的 API。
- com.ohos.formrenderservice 里报 can't find this page xxx.abc path。打包问题,检查 hap 包里 xxx.abc 是否存在、路径是否正确,然后 Build → Clean Project 重新编译。
- 白屏而不是不刷新。日志里 setFormOpacity 显示透明度被设到 0.005 这种极低值,内容就等于看不见;另外图片走共享内存有硬上限,API 20 起总大小 10MB、单次最多 20 张,API 19 及之前是 5 张、单张不超过 2MB,超了会 load SharedMemoryImage timeout!。
四、六步排查法,按顺序走最省时间
- 看配置。module.json5 里 type 必须是 "form"、metadata 的 resource 必须指向 $profile:form_config;form_config.json 里 updateEnabled 是否 true、updateDuration 与 scheduledUpdateTime 是否冲突、src 路径是否相对模块根目录写对。少一样就整体不生效。
- 看生命周期进没进来。在 onAddForm、onUpdateForm、onFormEvent 三个入口各打一行日志。没进来是路由 / 配置问题,进来了但数据旧才是数据问题 —— 这一步能把排查范围直接砍半。
- 看数据源是否同一份。抓 put 和 get 的 key、确认 flush() 被调用、确认卡片侧读的是同一个 preferences 文件名。八成问题在这里结束。
- 看 formId 是否有效。getFormsInfo 取当前列表,比对 updateForm 返回的错误码:16501001 是 formId 不存在,16501002 是卡片数量超上限,16501003 是无权操作该卡片,16500050/16500060 是 IPC 或服务连接问题,16500100 是取配置失败,16501000 是内部错误。
- 看卡片渲染进程日志。过滤 com.ohos.formrenderservice,查 abc 路径报错、Cannot get SourceMap info(不支持卡片的模块)、Get file size failed(图片没加载完就渲染)、load SharedMemoryImage timeout(图片量超限)。
- 看配额和频率。算一下当天定时刷新次数是否接近 50、是否叠加了 setFormNextRefreshTime、是否有高频 updateForm 被节流。跨天复测一次,如果第二天早上自动恢复,基本就是配额撞顶。
五、日志与错误码对照表
| 关键日志 / 错误码 | 含义 | 处理方向 |
|---|---|---|
| Cannot get SourceMap info, dump raw stack | 卡片进程执行出错,多为 API 不支持或业务变量为空 | 查 API 是否有 @form 标签;查空数组 / 空对象取值 |
| can't find this page xxx.abc path | 卡片页面产物路径不对 | 检查 hap 内 abc 文件,Clean 后重编 |
| setFormOpacity 数值极低 | 卡片被设成近乎透明 | 检查 opacity 设置 |
| load SharedMemoryImage timeout! | 图片超出共享内存限制 | 分批刷新,首屏只推关键图 |
| Get file size failed, errno is 0 | 图片未加载完就取 fd | 等资源就绪再 updateForm |
| 16501001 | formId 不存在 | 重新拉取有效卡片列表 |
| 16501002 | 卡片数量超上限 | 减少卡片或提示用户 |
| 16501003 | 当前应用无权操作该卡片 | 核对 bundleName / 模块归属 |
六、改完之后怎么验证,别只看 "现在刷了"
- 真机验证,不看预览器。预览器给的是初始值,@State 这类问题只有真机能暴露。
- 杀进程再进。验证持久化是否真的落盘,这一步能抓住 "忘了 flush"。
- 重启设备。验证 onAddForm 返回值与 updateForm 数据是否一致。
- 删卡片再加。验证 onRemoveForm 是否清理了旧 formId,新卡能不能正常刷。
- 跨天复测。验证 50 次配额是否被撞顶、第二天 0 点是否自动恢复。
- 后台切前台。验证 "不可见只记录、可见才刷布局" 这条行为是否符合预期。
把这套走完,你会发现卡片刷新这件事的难点根本不在 updateForm 这个接口,而在两个进程如何共享一份可信数据。机制层面只要把 updateEnabled、updateDuration 优先级、配额这三件事配对,剩下九成问题都落在 "数据有没有真正落盘、formId 还在不在、卡片 UI 收数据的装饰器写没写对" 这三个点上。排查顺序比技巧更重要:先确认生命周期进没进来,再确认数据是不是同一份,最后才去看渲染进程的日志 —— 顺序反了,就很容易在日志里绕半天,其实问题出在一行没写的 flush()。
【常见问题】
问题 1:鸿蒙桌面卡片设置了定时刷新还是不刷新,最可能是什么原因?
回答 1:先看 form_config.json 里的 updateEnabled 有没有设成 true—— 服务卡片(含元服务卡片)默认是关闭自动刷新的。如果已经是 true,再确认 updateDuration 的取值:单位是 30 分钟,填 0 等于关闭;同时配了 scheduledUpdateTime 时定时刷新优先,想用定点刷新必须把 updateDuration 设为 0。还有一种情况是当天 50 次定时刷新配额已经用完,表现就是下午开始不刷、第二天 0 点自动恢复。
问题 2:元服务卡片数据明明更新了,桌面卡片为什么还是旧数据?
回答 2:因为卡片进程和应用主进程是两套进程,卡片不读你内存里的变量。元服务卡片刷新前必须把数据落到持久化存储,preferences.put() 之后要调 flush() 才真正落盘,然后在 onUpdateForm 或 onFormEvent 里用 formProvider.updateForm() 推给卡片。如果卡片 UI 用的是 @State 而不是 @LocalStorageProp,推过去的数据也不会生效,这是预览器正常、真机不动的典型原因。
问题 3:鸿蒙卡片调用 updateForm 返回 16501001 是什么意思,怎么修?
回答 3:16501001 表示要操作的卡片 ID 不存在,通常是用户已经把这张卡片从桌面删掉,而应用还在用缓存的旧 formId 刷新。修法是刷新前用 getFormsInfo 拿到当前有效的卡片列表再推送,不要长期缓存 formId;同时在 onRemoveForm 回调里清理与这张卡片关联的数据。如果返回 16501002 是卡片数量超上限,16501003 是当前应用无权操作该卡片。
问题 4:鸿蒙桌面卡片刷新有次数上限吗,为什么下午就不刷了?
回答 4:有。每张卡片每天通过定时方式触发刷新最多 50 次,0 点重置,updateDuration 和 setFormNextRefreshTime 都计入这个配额。配 updateDuration: 1(30 分钟一次)一天理论 48 次,已经很接近上限,再叠加几次 "下次刷新" 就会撞顶。另外卡片不可见时系统只记录刷新动作和数据,等可见了才统一刷布局,所以后台看日志判断 "没刷新" 也可能是误判。
【参考资料】
[2026-11-16](鸿蒙桌面卡片为什么不刷新:一次元服务排查记录)阿里云开发者社区
[2026-11-11](ArkTS 卡片被动刷新:定时刷新、定点刷新、条件刷新与约束限制)华为开发者
[2026-11-11](配置 ArkTS 卡片的配置文件:form_config.json 字段说明与优先级)HarmonyOS 设备开发
[2026-11-11](formProvider.updateForm 接口说明与错误码)华为开发者
[2026-10-27](卡片数据同步异常:四类场景分析与修改建议)华为开发者
[2026-10-27](如何定位并解决卡片白屏展示的问题:日志关键字与图片共享内存限制)华为开发者
[2026-10-14](卡片更新与数据交互:定时、定点更新卡片最佳实践)华为开发者
[2026-06-26](元服务卡片刷新:updateEnabled 默认关闭自动刷新)华为开发者
【免责声明】
本文依据华为开发者官方文档、官方 FAQ 与公开技术实践整理,配置字段、刷新配额、API 版本支持范围均以官方文档当前版本为准,不同 API 版本(如 18、26.0.0)的行为存在差异,落地前请对照所用版本核对。文中日志关键字与错误码来自官方文档与开发者实测,实际日志内容会因设备与版本不同而变化。排查涉及删除卡片、清理数据等操作,请先在测试设备验证。本文不构成对任何第三方课程、工具或服务的推荐。
