鸿蒙桌面卡片为什么不刷新:一次元服务排查记录

简介: 桌面卡片(Form)是鸿蒙上很容易出彩、也很容易出问题的功能。最典型的现象是:应用里的数据明明变了,桌面上那张卡片还是昨天的。如果你想系统看一遍元服务和卡片这块——不同尺寸布局、卡片间数据共享、卡片跳转应用内页面,可以看看誉天教育的鸿蒙课,它第一阶段排的是 ArkTS 与开发环境、ArkUI 与状态管理、数据网络与权限、多端适配与 AI 入口四块,多端适配那一块把卡片和普通页面放在一起讲差异。

桌面卡片(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 入口四块,多端适配那一块把卡片和普通页面放在一起讲差异。

相关文章
|
17天前
|
Linux 开发工具 iOS开发
Codex保姆级教程(下载+安装+登录+使用,含所有版本,2026最新)
Codex是OpenAI推出的开源AI编程智能体,本地运行,可理解整个代码库,支持自然语言指令改代码、执行命令、跑测试、修Bug,兼容Win/macOS/Linux。(239字)
7155 54
|
4天前
|
JSON 前端开发 API
阿里云最新Qwen4-Max大模型介绍:模型定位、特征、能力、适用场景解析
2026 年 11 月 11 日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问 AI 平台 Token Plan,并同步接入千问办公、Qoder 等入口。该版本聚焦知识理解、世界感知、编程与 Agentic 四项升级,主打复杂编程、专业办公、前端设计与专业软件操作。预览期至 11 月 25 日 24:00,到期后模型标识下线;限时 2 折、新用户再享 5 折,最低 1 折可体验。
|
5天前
|
云安全 人工智能 安全
|
18天前
|
JavaScript API iOS开发
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(DSH)是DeepSeek于2026年开源的MIT协议AI Agent框架,支持插件化组装模型、工具、沙箱与UI,兼容主流大模型。本文提供免Node.js的桌面端安装包(Win/macOS),含详细图文教程及热门插件推荐。
5516 66
|
12天前
|
Linux 开发工具 iOS开发
2026最新codex下载安装保姆级使用教程(下载+安装+登录+使用,含所有历史版本)
本文详解OpenAI Codex国内快速上手指南:提供Win/macOS/Linux全平台免安装包、npm/Homebrew等多方式安装、账号/API Key双登录、简体中文切换,覆盖下载、安装、汉化、使用及高频避坑(如微软商店失败、npm超时等),10分钟即可跑通。
2783 9
|
4天前
|
人工智能 前端开发 API
阿里云Qwen4-Max 大模型详解:定位、特征、能力、适用场景与相对Qwen3-Max差异解析
2026年11月11日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问AI平台Token Plan并接入千问办公、Qoder等入口。该版本聚焦知识理解、世界感知、编程与Agentic四项升级,主打复杂编程、专业办公、前端设计与专业软件操作等真实任务。预览期为11月11日10:00至11月25日24:00,仅支持Token Plan调用,到期后模型标识下线;限时2折、新用户再享5折,最低1折可体验。
|
10天前
|
人工智能 安全 API
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(dsh)是DeepSeek AI于2026年开源的轻量级Agent运行框架,基于Cordis内核,践行“一切皆插件”理念。支持Web/桌面双端,开箱即用;内置多模型接入、丰富插件生态(超3.5万),适配编程、办公、创作等场景。(239字)
1802 1
|
2天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
1261 0
|
8天前
|
人工智能 iOS开发 开发者
2026年 Codex 下载地址更新:codexdown.cn 已更换为 codexdown.cc(附 Codex 客户端下载)
2026年Codex官方下载站已由codexdown.cn正式迁移至codexdown.cc,提供Windows/macOS最新客户端、历史版本、安装教程及配置指南,开发者可一站式获取稳定、安全、签名验证的AI编程工具资源。(239字)
1675 0