相信不少做鸿蒙应用开发的朋友都遇到过这个场景桌面小组件上明明已经显示了数据但点进应用后页面却没拿到对应参数或者应用里更新了状态桌面上那个卡片还是旧数据怎么刷新都没反应。这类问题的根源几乎都集中在小组件与主应用之间的数据传递上。鸿蒙里的“小组件”官方叫法其实是 ArkTS 卡片Form它和主应用跑在完全不同的进程或渲染节点里所以你不能像平时写页面那样直接拿一个全局变量去共享数据。这篇文章我就基于实际踩坑经验把 ArkTS 卡片和主应用之间常见的数据传递方式、适用场景、以及那些文档里不会明说的限制一次性说清楚。1. 先搞清楚卡片到底跑在哪儿理解进程边界很多新手第一次写卡片就懵原因在于下意识把它当成“一个小页面”来写。实际上 ArkTS 卡片由 FormExtensionAbility 提供它跟主 UIAbility 是两套独立的东西。卡片运行在独立的 Form 进程或渲染进程里和主应用之间不存在共享内存空间。这就决定了你不能像普通单页面那样“直接读一个全局变量”或者“直接调一个单例方法”。1.1 为什么不能像普通页面那样共享数据传统应用内数据共享比如 Ablity 之间的 dataAbility或者组件间的 State 父子传参前提是它们跑在同一个沙箱里。一旦拆成卡片和主应用两个进程常规手段就全部失效。我最早做卡片时试过直接把一个 module 级变量在卡片页面里 import结果发现卡片进程里那个变量永远是初始值主应用怎么改都影响不到它——两边的内存都不在同一份自然读不到。卡片和主应用的关系正确的理解方式是“两个独立应用模块之间的协作”。主应用更新数据后必须主动“推”给卡片卡片想通知主应用也只能通过拉起或者发消息的方式“单向送信”而不是双向访问。这个认知一旦建立后面所有方案就都顺了。1.2 卡片的生命周期决定数据从哪里来卡片的生命周期是由系统管理而不是由主应用管理。用户把卡片添加到桌面时系统会调用 FormExtensionAbility 的 onAddForm卡片被移除时调用 onRemoveForm主应用想刷新卡片内容时可以调用 FormProvider 的 updateForm。整个过程里卡片页面本身不会主动去“拉”主应用的数据——它只能被动接收或者依靠本地存储自己读。所以梳理数据传递方案时必须先想清楚一个问题数据是谁在什么时候产生的主应用产生、卡片消费那就用推送存储卡片产生、主应用消费那就用消息拉起两边随时要保持同步那就得靠持久化存储。不同的数据流向对应完全不同的实现方式。2. ArkTS卡片与主应用数据传递的四种主流方案这一节直接上干货。我按实际开发中最高频的四种场景来拆解每种都会给出选型理由和核心 API你可以直接对着自己的需求挑方案。2.1 LocalStorage / AppStorage适合单进程内的 UI 状态同步如果你开发的卡片是“仅在一个进程内使用”的简单场景比如卡片页面内部状态需要跨组件共享LocalStorage 和 AppStorage 是最轻量的选择。它本质是 UI 级的状态存储可以让卡片页面里的多个组件共享同一个数据源。// 卡片页面中创建 LocalStorage let storage new LocalStorage(); storage.setOrCreate(taskCount, 12); Entry(storage) Component struct CardWidget { LocalStorageProp(taskCount) taskCount: number 0; // 卡片 UI 中直接绑定 taskCount }但这里必须特别强调LocalStorage 和 AppStorage 只在同一个进程内有意义。如果你的卡片进程和主应用进程是分离的那主应用修改 AppStorage 的值卡片进程里的 AppStorage 根本感知不到。很多朋友在这个地方反复踩坑以为全局存储是“全局互通”实际上它只在同一个 Ability 或同一批组件实例内有效。所以我在实际开发中只在卡片页面内部组件较多时才用它跨进程传递一律不用。2.2 postCardAction卡片向主应用发送消息的唯一原生通道postCardAction 是卡片主动通知主应用最重要的接口。它可以在卡片内部通过点击事件触发比如用户点了卡片上的某个按钮卡片调用 postCardAction 让系统拉起主应用同时携带一串自定义参数。主应用被拉起后在 onNewWant 或 onCreate 里就能拿到这份参数。// 卡片侧触发 postCardAction Button(立即处理) .onClick(() { postCardAction({ action: router, bundleName: com.example.myapp, abilityName: EntryAbility, params: { taskId: 1001, from: card } }); })这套机制本质是“卡片 → 主应用”的单向消息系统拿到 action 后会拉起目标 Ability并把 params 原样带过去。它可以实现从桌面卡片一键跳转到 App 内指定页面并且完成参数传递。2.3 Preferences / 关系型数据库跨进程共享的“公开信箱”如果主应用和卡片都需要读写同一份数据又不想依赖网络持久化存储就是最可靠的选择。鸿蒙的 Preferences轻量级偏好存储和关系型数据库都是落盘存储任何进程都能读天然适合跨进程共享。// 主应用写入 Preferences let preferences await dataPreferences.getPreferences(context, myStore); await preferences.put(taskCount, 12); await preferences.flush(); // 卡片进程读取同 key let cardPrefs await dataPreferences.getPreferences(context, myStore); let count await cardPrefs.get(taskCount, 0);注意这个方案的坑点Preferences 的操作是异步的卡片页面在 onPageShow 或 aboutToAppear 里读数据时必须用 async/await 处理不能直接卡 UI 线程去同步等待。另外如果主应用刚写入还没来得及 flush卡片马上读取可能读到旧值。所以每次写入后务必调用 flush() 确保落盘。2.4 FormProvider.updateForm主应用主动刷新卡片视图主应用数据发生变化后想让卡片上的 UI 同步更新核心就是 FormProvider 的 updateForm。它带一个 FormBindingData 对象里面是键值对形式的参数卡片侧可以在 LocalStorage 或 StorageProp 里绑定对应 key 来实现 UI 联动更新。// 主应用更新卡片 let formData new formBindingData.FormBindingData({ taskCount: 13, taskName: 完成周报 }); formProvider.updateForm(formId, formData) .then(() { // 更新成功的回调 }) .catch((err) { // 更新失败一般是 formId 无效或卡片已移除 });这是主应用向卡片“推数据”的主流方式效率高不需要卡片侧主动轮询。但要注意updateForm 也不是无限频次随便调的频繁调用会触发系统的频率限制严重的甚至会被系统判定为异常行为。实际项目里的经验是按业务节奏更新比如任务状态变更、用户手动刷新时触发即可不要写一个定时器每秒钟刷一次。3. 实操一个可以照抄的“任务清单卡片”示例方案光看容易晕我直接给出一个完整示例覆盖“添加卡片 → 主应用更新数据 → 卡片展示数据 → 点击卡片回跳主应用并传参”这条完整链路。这个场景在待办事项、日程提醒、快递跟踪之类的小组件里相当通用。3.1 创建卡片配置 FormExtensionAbility 和卡片页面先在工程的 module.json5 里声明卡片扩展能力并指定卡片页面入口。这是整个卡片功能的基础。// module.json5 片段 { extensionAbilities: [ { name: TaskCardFormExtension, srcEntry: ./ets/forms/TaskCardFormExtension.ets, label: $string:task_card_label, type: form, metadata: [ { name: ohos.extension.form, resource: $profile:form_config } ] } ] }然后准备 form_config.json这里的 dimensions 是卡片尺寸规格比如 2x2 表示小尺寸卡片name 是卡片的唯一标识。// form_config.json { forms: [ { name: TaskCard, displayName: $string:task_card_name, description: $string:task_card_desc, src: ./ets/forms/TaskCardPage.ets, uiSyntax: arkts, window: { designWidth: 720, autoDesignWidth: true }, colorMode: auto, isDefault: true, updateEnabled: true, scheduledUpdateTime: 10:30, updateDuration: 1, defaultDimension: 2*2, supportDimensions: [2*2] } ] }这里的 updateEnabled 和 updateDuration 表示允许系统定时刷新卡片但刷新只是触发卡片页面重新加载并不是自动拉取主应用的数据。关键还是靠 FormProvider 主动推送。3.2 卡片扩展类处理新增、删除、刷新FormExtensionAbility 是整个卡片的数据入口它负责响应系统的事件回调。最核心的是 onAddForm它返回卡片要渲染的初始数据。// TaskCardFormExtension.ets import formExtension from ohos.app.ability.FormExtensionAbility; import formBindingData from ohos.app.ability.formBindingData; import dataPreferences from ohos.data.preferences; export default class TaskCardFormExtension extends formExtension { async onAddForm(want) { // 读取持久化存储中的任务数据 let preferences await dataPreferences.getPreferences(this.context, taskStore); let taskCount await preferences.get(taskCount, 0); let taskName await preferences.get(taskName, 暂无任务); // 构造卡片渲染所需数据 let formData new formBindingData.FormBindingData({ taskCount: taskCount, taskName: taskName }); return formData; } onRemoveForm(formId) { // 卡片被移除时的清理工作 console.info(卡片移除 formId${formId}); } }onAddForm 返回的 FormBindingData 里如果带上了对应的 key卡片页面的 LocalStorage 初值就会被这些值覆盖。这也是卡片第一次显示时为什么能立刻看到主应用历史数据的原因——它读的是持久化存储里已经存在的内容。3.3 卡片页面绑定数据并处理点击回跳卡片页面的写法和普通页面很像区别在于它基于 FormExtensionAbility 的渲染上下文组件能力有一定限制比如不支持所有系统组件动画、弹窗之类会受限。数据绑定用 LocalStorageProp 或 StorageProp 来接收 FormBindingData 传过来的 key。// TaskCardPage.ets Entry Component struct TaskCardPage { LocalStorageProp(taskCount) taskCount: number 0; LocalStorageProp(taskName) taskName: string 暂无任务; build() { Column({ space: 8 }) { Text(this.taskName) .fontSize(16) .fontWeight(FontWeight.Bold) .maxLines(1) .textOverflow({ overflow: TextOverflow.Ellipsis }) Text(${this.taskCount} 项待办) .fontSize(14) .fontColor(#666666) Button(查看详情) .onClick(() { postCardAction({ action: router, bundleName: com.example.myapp, abilityName: EntryAbility, params: { page: TaskDetail, taskCount: this.taskCount } }); }) } .padding(16) .width(100%) .height(100%) } }这里的关键点是 postCardAction 的 params 就是你要传给主应用的数据。它等同于你从卡片给主应用“口信”主应用拉起后在 onNewWant 里就能拿到这个 params。我在项目里通常会在 params 里再带一个来源字段比如 from: card方便主应用区分是用户直接从桌面点进来的还是从卡片回跳进来的这样页面可以针对性地做不同交互。3.4 主应用侧接收参数并更新卡片数据主应用被卡片拉起后在 UIAbility 的 onNewWant 或 onCreate 里处理参数。需要注意的是如果应用已经存在并驻留后台系统走的是 onNewWant如果应用被完全杀死后由卡片拉起则走 onCreate。两个生命周期里都要做参数解析否则会出现“点卡片没反应”或“参数丢失”的情况。// EntryAbility.ets 关键代码 import UIAbility from ohos.app.ability.UIAbility; export default class EntryAbility extends UIAbility { onNewWant(want, launchParam) { let params want.parameters; if (params params.from card) { // 来自卡片的跳转加载对应页面 this.context.router.pushUrl({ url: pages/TaskDetail, params: { taskCount: params.taskCount } }); } } onCreate(want, launchParam) { // 冷启动场景也要解析 let params want?.parameters; if (params params.from card) { this.loadCardParams(params); } } }然后就是主应用内数据变化时调用 FormProvider.updateForm 反向更新卡片。比如用户在主应用里把待办数量从 12 改成 13并希望桌面卡片同步变化async function updateTaskCard(formId: string, taskCount: number, taskName: string) { // 先把最新数据写入 Preferences这样卡片冷启动时也能读到 let preferences await dataPreferences.getPreferences(getContext(this), taskStore); await preferences.put(taskCount, taskCount); await preferences.put(taskName, taskName); await preferences.flush(); // 再主动推卡片实时刷新 let formData new formBindingData.FormBindingData({ taskCount: taskCount, taskName: taskName }); try { await formProvider.updateForm(formId, formData); } catch (error) { console.error(更新卡片失败 code${error.code}); } }这里有个很容易被忽略的小细节updateForm 的 formId 从哪来如果主应用在运行过程中没保存过 formId它就拿不到正在桌面展示的卡片实例。所以正确做法是在 onAddForm 回调里把 formId 存到 Preferences 或应用中后续更新时用这个 id。多个卡片就需要存多个 id更新时逐个遍历。4. 那些文档里没写清楚的坑与排查思路数据传递的方案本身不难难的是各种奇奇怪怪的边界情况。这一节我把实际开发中遇到的高频问题整理一下并给出排查思路方便你遇到类似情况时少走弯路。4.1 主应用刚更新数据卡片还是旧值这个问题的本质是更新链路没有走完。最常见的原因是 updateForm 之前没有把数据真正写入卡片能读到的地方。卡片有两个数据来源一个是 AddForm 时返回的 FormBindingData一个是 updateForm 时重新推的 FormBindingData。如果你希望卡片能同时响应“实时推送”和“冷启动恢复”两处都要覆盖到位。排查步骤确认 updateForm 的 promise 是否成功如果返回错误码查 formId 是否还有效确认卡片页面绑定的是 LocalStorageProp 而不是普通 State确认主应用确实写入了 Preferences 并调用了 flush提示卡片进程是独立的你修改主应用里的 Preferences 值后卡片进程不会自动感知必须通过 updateForm 重新推送或者让卡片重新启动才能读到新值。4.2 点击卡片拉起主应用但没有拿到参数这种情况多半是生命周期判断出了问题。应用在后台存活时点击卡片走的是 onNewWant应用被清理后重新拉起走的是 onCreate。如果你只在 onNewWant 里处理冷启动时间必然丢参数反过来如果你只在 onCreate 里处理热启动场景同样会丢。我的处理习惯是做一个统一的 parseWantParams 方法在两个生命周期里分别调用并且在 onCreate 里判断一下是否已经初始化过页面。如果初始化过就跳过重复加载避免页面被多次创建。4.3 卡片里读不到 Preferences或者读到的是空值Preferences 的 context 问题特别容易踩。卡片扩展里拿到的 this.context 和主应用页面里拿到的 context 是不同的实例但 Preferences 存储基于文件路径只要同一个应用包名下路径一致就能读写同一份文件。实际上更常见的错误是路径不一致或者没有正确等待异步回调。另外一个隐藏问题Preferences 是异步读取卡片页面在 aboutToAppear 里发起读取时UI 已经开始渲染了。如果读取慢一点页面可能先渲染了默认值 0然后才被异步结果刷新。这种“闪一下默认值”的体验在卡片上特别明显。我的做法是先读 Preferences拿到值后再把数据 set 到 LocalStorage最后再渲染 UI或者直接在 FormExtension 的 onAddForm 里就把数据读出来通过 FormBindingData 给到页面这样页面第一次渲染时就有正确数据不会闪。4.4 updateForm 频繁调用被系统限流鸿蒙对表单更新频率有保护机制短时间内高频调用 updateForm可能触发系统限制表现为更新失败或者部分卡片不刷新。这个限制具体阈值依赖系统版本不一定完全一致但实际项目里我建议避免在主应用每个页面 onShow 时都去 updateForm只在关键数据变化任务完成、状态切换、列表变更时更新如果有批量更新同一张卡片的多个字段合并成一次 FormBindingData 推送不要多次调用4.5 多个卡片的 formId 管理混乱同一张卡片用户可能添加多份到桌面每份都有独立 formId。如果你只存了一个 formId那只能刷新到一份卡片。正确做法是在 onAddForm 时把 formId push 进一个数组并持久化onRemoveForm 时移除对应 id。后续更新时遍历整个数组逐个 updateForm。需要注意频繁遍历可能会导致部分卡片在删除后 still 调用更新增加错误日志所以每个 id 更新前都做个 try/catch 比较稳妥。4.6 真机调试时卡片黑屏或白屏卡片开发最难受的就是调试。IDE 模拟器没法完全模拟桌面卡片的真实生命周期经常模拟器正常、真机就白屏。白屏的原因一般是卡片页面用了不支持的组件或属性比如部分动画 API卡片页面数据异常渲染时报错但卡片进程里日志不容易看到form 配置里 src 路径写错排查方法真机连接后在 Log 面板过滤 “Form” 关键字能定位到很多卡片进程的报错信息。也可以临时在卡片页面 aboutToAppear 里加日志打点输出到控制台。开发阶段可以把卡片入口简单化先渲染一行纯文本验证数据通路通了再逐步加复杂 UI这样能最大限度缩小问题范围。5. 实践中的选型建议与后续扩展思路我在实际项目中总结了一套比较稳妥的选型规则你可以直接套用主应用 → 卡片单向下发优先 FormProvider.updateForm配合持久化存储兜底冷启动卡片 → 主应用单向通知用 postCardAction通过 params 携带数据主应用和卡片双向频繁同步持久化存储为主updateForm 做 UI 增量刷新卡片内部多组件状态共享用 LocalStorage别用全局变量从扩展角度讲如果你的卡片数据来自服务端主应用可以先拉取网络数据再写入 Preferences同时调用 updateForm 更新卡片。这样即使主应用不打开卡片只要被系统刷新也能读到本地缓存的最新值。这个模式本质上就是“服务端 → 主应用 → 卡片”的推拉结合。如果项目里有多个卡片需要共享同一份数据可以考虑提取一个数据管理模块比如单例 DataManager统一封装读写和更新逻辑。卡片侧和主应用侧都 import 同一份代码虽然是两个进程各自持有实例但因为底层共用同一份持久化文件数据语义上仍然是统一的。我个人在实际操作中体会最深的一点是不要试图让卡片和主应用“实时同步得像一个应用”因为它们的运行模型从底层就决定了无法做到真正的内存级共享。正确的做法是接受进程隔离这个事实把数据放在“边界”上——持久化文件、系统消息、推送通道——然后用事件去驱动 UI 更新。想清楚这一点所有传递问题都能迎刃而解。最后再分享一个小技巧开发阶段把卡片数据源单独抽成一个接口不管是 Preferences、数据库还是未来换成分布式数据都只改实现不动页面代码。这样等你需要适配更多设备形态或者跨端同步时改动成本会小很多。
