042-Form Kit服务卡片

042 — Form Kit 服务卡片从 2x2 到 4x4 的桌面数据展示实践简介服务卡片是鸿蒙系统的标志性能力之一它让用户无需打开应用就能在桌面上快速查看关键信息。MoneyTrack 利用 Form Kit 实现了两种尺寸的桌面卡片2x2 的迷你卡片MiniCard展示当日收支概览4x4 的中间卡片MiddleCard展示月度趋势图表。通过 FormExtensionAbility 生命周期管理、form_config.json 配置和定时刷新机制用户可以在桌面上实时掌握自己的财务状况。form_config.json 完整配置卡片的元信息在form_config.json中声明开发者在module.json5中通过formConfigPath字段引用该文件。以下为完整配置项说明配置项类型必填说明namestring是卡片名称在同一应用中唯一dimensionstring是卡片尺寸支持1x2、2x2、2x4、4x4descriptionstring否卡片描述用于系统界面展示updateEnabledboolean否是否启用定时刷新默认 falsescheduledUpdateTimestring否定时刷新时间格式HH:mm需配合 updateEnabledupdateDurationnumber否刷新间隔单位分钟最小 30 分钟formConfigAbilitystring否卡片配置页的 ability 名称landscapeLayoutstring否横屏布局文件的模块名isContainerboolean否是否为容器卡片默认 falsemultiUserEnabledboolean否是否支持多用户场景默认 false{forms:[{name:mini_card,dimension:2x2,description:当日收支概览,updateEnabled:true,scheduledUpdateTime:10:00,updateDuration:60,formConfigAbility:FormConfigAbility},{name:middle_card,dimension:4x4,description:月度收支趋势,updateEnabled:true,scheduledUpdateTime:08:00,landscapeLayout:MiddleCardLandscape}]}FormExtensionAbility 完整生命周期FormExtensionAbility 是卡片的后端逻辑载体管理卡片的完整生命周期。开发时需要继承该类并重写对应方法import{FormExtensionAbility,formBindingData}fromkit.FormKit;import{Want}fromkit.AbilityKit;exportdefaultclassMiniCardextendsFormExtensionAbility{// 用户将卡片添加到桌面时触发onAddForm(want:Want):formBindingData.FormBindingData{consttodayDatathis.getTodaySummary();returnformBindingData.createFormBindingData(todayData);}// 定时更新或系统触发更新时调用onUpdateForm(formId:string){constnewDatathis.getTodaySummary();this.updateForm(formId,formBindingData.createFormBindingData(newData));}// 用户从桌面移除卡片时触发用于清理资源onRemoveForm(formId:string){console.info(Form${formId}removed, cleaning up resources.);this.releaseDataConnection(formId);}// 用户点击卡片上的交互组件如按钮时触发onFormEvent(formId:string,message:string){if(messagerefresh){this.onUpdateForm(formId);}elseif(message.startsWith(navigate:)){constpagemessage.split(:)[1];this.navigateToPage(page);}}}四个生命周期方法的职责明确onAddForm负责初始化数据绑定onUpdateForm负责数据刷新onRemoveForm负责资源释放onFormEvent负责响应卡片上的用户交互事件。卡片数据刷新策略服务卡片的数据更新支持两种策略定时刷新通过updateEnabled和scheduledUpdateTime或updateDuration配置系统会在指定时间或间隔自动拉起 FormExtensionAbility 执行onUpdateForm。此方式实现简单但刷新频率受系统限制最小间隔 30 分钟且用户不可见时可能被系统延迟触发。主动推送应用在业务逻辑中通过formProvider.updateForm(formId, formBindingData)主动推送数据到已添加的卡片。此方式实时性高适合数据变化时需要立即更新的场景如记账后刷新卡片。使用前需先通过formProvider.getFormsInfo()查询当前已添加的卡片列表。import{formProvider,formBindingData}fromkit.FormKit;// 记账完成后主动刷新所有卡片asyncfunctionrefreshAllForms(){constformsawaitformProvider.getFormsInfo();for(constformofforms){constdataformBindingData.createFormBindingData({todayIncome:getTodayIncome(),todayExpense:getTodayExpense()});awaitformProvider.updateForm(form.formId,data);}}卡片生命周期流程卡片UIFormExtensionAbility桌面系统用户卡片UIFormExtensionAbility桌面系统用户定时刷新触发用户交互移除卡片长按桌面选择添加卡片创建 FormExtension 实例onAddForm(want) 初始化数据返回 FormBindingData渲染卡片 UI显示卡片内容onUpdateForm(formId)获取最新数据更新 FormBindingData刷新 UI 展示点击卡片按钮onFormEvent(formId, message)处理交互事件移除桌面卡片onRemoveForm(formId)清理资源卡片的运行限制服务卡片运行在受限环境中以保证系统性能和功耗资源限制卡片进程的内存上限较低约 20MB不应在卡片中执行大量数据计算或加载大图片。建议采用数据在应用中预处理卡片仅做展示的设计模式。API 限制卡片中无法使用全部 Ace 组件和 API。受限能力包括不支持网络请求需通过 FormExtensionAbility 代理、不支持本地存储读写需通过应用主进程提供数据、不支持弹窗和 Toast、不支持setInterval等高频率定时器、不支持Canvas完整绘图能力仅支持基础图形。生命周期限制卡片长时间不可见时系统可能回收卡片资源应用进程被杀死后卡片仍能显示最后更新的快照数据但交互事件无法响应。最佳实践按需选择刷新策略每日一次的数据如日账单概览用定时刷新用户操作后立即更新的场景用主动推送。控制卡片复杂度2x2 卡片聚焦 1-2 个核心数值4x4 卡片增加图表和分类避免过度拥挤。善用 onFormEvent通过 message 参数实现卡片轻交互如点击刷新图标更新数据、点击详情跳转应用内页面。兜底数据设计卡片应设计无数据时的默认占位 UI避免首次添加时显示空白。资源按需释放在 onRemoveForm 中及时取消网络监听、断开数据库连接避免内存泄漏。项目代码案例文件路径entry/src/main/ets/FormAbility/MiniCard.ets2x2 卡片import{FormExtensionAbility,formBindingData,formProvider}fromkit.FormKit;import{Want}fromkit.AbilityKit;exportdefaultclassMiniCardextendsFormExtensionAbility{onAddForm(want:Want){consttodayDatathis.getTodaySummary();returnformBindingData.createFormBindingData(todayData);}onUpdateForm(formId:string){constnewDatathis.getTodaySummary();this.updateForm(formId,formBindingData.createFormBindingData(newData));}onRemoveForm(formId:string){console.info(MiniCard${formId}removed.);}onFormEvent(formId:string,message:string){if(messageaction_refresh){this.onUpdateForm(formId);}}privategetTodaySummary(){return{todayIncome:¥1,200,todayExpense:¥356};}}推荐参考文档Form Kit 服务卡片指南form_config.json 配置参考卡片开发最佳实践