鸿蒙中 卡片交互：message事件（三）

本文同步发表于我的微信公众号微信搜索程语新视界即可关注每个工作日都有文章更新之前介绍了router事件页面跳转和call事件后台服务今天聊聊第三种事件类型——message事件。message事件是卡片开发中最常用的事件类型适用于点击卡片按钮刷新数据卡片与应用之间的消息通信触发应用后台更新卡片内容一、message事件message事件是postCardAction接口支持的一种事件类型用于卡片向卡片提供方应用发送消息。message事件的工作流程卡片点击 │ ▼ postCardAction({ action: message, params: {...} }) │ ▼ 系统拉起FormExtensionAbility如果未运行 │ ▼ 触发FormExtensionAbility的onFormEvent生命周期回调 │ ▼ 在onFormEvent中处理消息、获取新数据 │ ▼ 调用updateForm接口刷新卡片 │ ▼ 卡片收到新数据更新显示三种事件对比事件类型目标作用适用场景routerUIAbility前台页面跳转点击卡片进入应用详情页callUIAbility后台后台服务调用音乐播放控制、后台任务messageFormExtensionAbility消息传递数据刷新、状态同步message事件的特点目标是FormExtensionAbility卡片扩展能力主要用于触发数据刷新不会显示UI界面二、代码示例点击按钮刷新卡片2.1 卡片页面布局// entry/src/main/ets/updatebymessage/pages/UpdateByMessageCard.ets // 创建LocalStorage用于数据共享 let storageUpdateByMsg new LocalStorage(); Entry(storageUpdateByMsg) Component struct UpdateByMessageCard { // 通过LocalStorageProp接收卡片提供方推送的数据 // 初始值为资源文件中的默认值 LocalStorageProp(title) title: ResourceStr $r(app.string.default_title); LocalStorageProp(detail) detail: ResourceStr $r(app.string.DescriptionDefault); build() { Column() { // 上半部分标题和详情显示区域 Column() { Text(this.title) .fontColor(#FFFFFF) .opacity(0.9) .fontSize(14) .margin({ top: 8%, left: 10% }) Text(this.detail) .fontColor(#FFFFFF) .opacity(0.6) .fontSize(12) .margin({ top: 5%, left: 10% }) } .width(100%) .height(50%) .alignItems(HorizontalAlign.Start) // 下半部分刷新按钮 Row() { Button() { Text($r(app.string.update)) .fontColor(#45A6F4) .fontSize(12) } .width(120) .height(32) .margin({ top: 30%, bottom: 10% }) .backgroundColor(#FFFFFF) .borderRadius(16) .onClick(() { // 点击按钮时通过postCardAction发送message事件 postCardAction(this, { action: message, params: { msgTest: messageEvent // 自定义消息参数 } }); }) } .width(100%) .height(40%) .justifyContent(FlexAlign.Center) } .width(100%) .height(100%) .alignItems(HorizontalAlign.Start) .backgroundImage($r(app.media.CardEvent)) .backgroundImageSize(ImageSize.Cover) } }说明字段说明LocalStorageProp接收卡片提供方推送的数据用于UI更新action: message指定事件类型为messageparams自定义消息参数可在FormExtensionAbility中获取2.2 导入所需模块// entry/src/main/ets/entryformability/EntryFormAbility.ts import { formBindingData, FormExtensionAbility, formProvider } from kit.FormKit; import { Configuration, Want } from kit.AbilityKit; import { BusinessError } from kit.BasicServicesKit; import { hilog } from kit.PerformanceAnalysisKit; const TAG: string EntryFormAbility; const DOMAIN_NUMBER: number 0xFF00;2.3 实现FormExtensionAbility// entry/src/main/ets/entryformability/EntryFormAbility.ts export default class EntryFormAbility extends FormExtensionAbility { // 处理卡片发送的message事件 onFormEvent(formId: string, message: string): void { hilog.info(DOMAIN_NUMBER, TAG, FormAbility onFormEvent, formId ${formId}, message: ${message}); // 定义新数据结构必须与卡片布局中的字段对应 class FormDataClass { title: string Title Update.; // 新标题 detail: string Description update success.; // 新详情 } // 创建新数据 let formData new FormDataClass(); let formInfo: formBindingData.FormBindingData formBindingData.createFormBindingData(formData); // 调用updateForm刷新卡片 formProvider.updateForm(formId, formInfo) .then(() { hilog.info(DOMAIN_NUMBER, TAG, FormAbility updateForm success.); }) .catch((error: BusinessError) { hilog.error(DOMAIN_NUMBER, TAG, Operation updateForm failed. Cause: ${JSON.stringify(error)}); }); } // 其他生命周期方法可选 onAddForm(want: Want): formBindingData.FormBindingData { // 添加卡片时的初始化数据 let obj: Recordstring, string { title: Initial Title, detail: Initial Description }; return formBindingData.createFormBindingData(obj); } onUpdateForm(formId: string): void { // 定时刷新触发如果有配置 hilog.info(DOMAIN_NUMBER, TAG, onUpdateForm); } onRemoveForm(formId: string): void { // 卡片移除时清理资源 hilog.info(DOMAIN_NUMBER, TAG, onRemoveForm); } }说明方法/字段说明onFormEventmessage事件触发时的回调formId触发事件的卡片IDmessage卡片发送的消息内容即params的JSON字符串updateForm更新卡片数据的接口FormDataClass数据结构必须与卡片中的LocalStorageProp字段对应2.4 配置资源文件// entry/src/main/resources/zh_CN/element/string.json { string: [ { name: default_title, value: Title default. // 默认标题 }, { name: DescriptionDefault, value: Description default. // 默认描述 }, { name: update, value: 刷新 // 按钮文字 } ] }三、运行效果状态标题描述初始状态Title default.Description default.点击刷新后Title Update.Description update success.四、参数传递4.1 卡片发送复杂参数// 卡片中发送带多个参数的消息 postCardAction(this, { action: message, params: { type: refresh, userId: 12345, timestamp: Date.now(), config: { autoRefresh: true, interval: 3000 } } });4.2 FormExtensionAbility接收参数onFormEvent(formId: string, message: string): void { // message是params对象的JSON字符串 hilog.info(0xFF00, TAG, 原始消息: ${message}); // 解析JSON字符串为对象 try { let params JSON.parse(message); let type params.type; // refresh let userId params.userId; // 12345 let timestamp params.timestamp; // 时间戳 let config params.config; // { autoRefresh: true, interval: 3000 } hilog.info(0xFF00, TAG, type: ${type}, userId: ${userId}); // 根据参数执行不同逻辑 if (type refresh) { this.refreshUserData(formId, userId); } } catch (error) { hilog.error(0xFF00, TAG, 解析消息失败: ${error}); } } private refreshUserData(formId: string, userId: string) { // 获取用户数据... let userData this.fetchUserData(userId); // 更新卡片 let formData formBindingData.createFormBindingData({ title: userData.name, detail: userData.status }); formProvider.updateForm(formId, formData); }五、与主动刷新的对比5.1 触发方式对比刷新方式触发方触发时机适用场景主动刷新应用自身数据变化时后台数据更新、推送消息message事件卡片用户用户点击时用户手动刷新、交互操作5.2 代码对比// 主动刷新应用自己调用 formProvider.updateForm(formId, formData); // message事件卡片触发应用响应 // 卡片中 postCardAction({ action: message }); // 应用中 onFormEvent() { // 处理并调用updateForm formProvider.updateForm(formId, formData); }六、注意事项限制项说明FormExtensionAbility生命周期被拉起后仅能存在5秒需在此时间内完成操作数据大小符合卡片刷新限制API 20 10MB/20张图片参数格式message是JSON字符串需要自行解析