HarmonyOS技术精讲-Form Kit（卡片开发服务）第1篇：初识Form Kit——卡片开发的基础概念

HarmonyOS技术精讲-Form Kit卡片开发服务第1篇初识Form Kit——卡片开发的基础概念开篇为什么需要Form Kit在HarmonyOS开发中“卡片”是一种轻量级的UI呈现方式用户无需打开应用就能在桌面或负一屏看到应用的关键信息并完成简单交互。很多人在第一次接触卡片开发时会疑惑这到底是一个Ability还是Widget开发时应该用ArkTS还是JS为什么我的卡片在桌面上显示不了这些问题背后的核心是Form Kit卡片开发服务。它定义了一套完整的框架让应用能够向系统桌面、负一屏等地方提供可动态更新的UI片段。本文先帮你建立全局认知后续再深入实战。它解决什么问题卡片的本质是“应用在系统桌面上的快捷窗口”。它可以展示实时信息天气、日历、待办提供快捷操作播放控制、计时器无需启动主Ability降低交互成本不适合的场景复杂交互、长表单、视频播放。卡片推荐尺寸有限2×2、4×4等且生命流程与宿主Ability独立。与传统的Widget如Android AppWidget相比HarmonyOS的Form Kit在生命周期绑定、更新机制和多端适配上做了更细化的设计。核心概念提供方与使用方角色说明对应组件提供方真正提供卡片UI和数据的应用FormExtensionAbility 卡片UI页面使用方显示卡片的系统界面桌面、负一屏、其他支持卡片的应用一张卡片从创建到销毁需要经历以下流程用户添加卡片→ 使用方请求提供方创建卡片实例。提供方返回卡片内容→ 通过FormExtensionAbility的onCreate回调返回绑定数据。使用方渲染卡片→ 基于ArkUI或JS框架渲染并定期或按需更新。卡片交互→ 用户点击卡片可触发click事件跳转或更新。卡片销毁→ 用户移除卡片时调用onDestroy清理。ArkTS卡片 vs JS卡片如何选择HarmonyOS提供两种卡片开发范式ArkTS卡片推荐和JS卡片已逐步废弃。对比项ArkTS卡片JS卡片语言ArkTSTypeScript超集JavaScript/AceUI框架ArkUI声明式JS模板语法特性支持动画、自定义绘制、双向通信仅基础组件和简单事件更新机制支持本地和远程更新可控制刷新频率受限建议用定时更新性能更好编译优化中等官方推荐是新项目必选否仅维护已有项目实际开发建议如果从零开始直接选择ArkTS卡片。JS卡片的生命周期和UI更新限制较多遇到复杂需求容易踩坑。Form Kit框架组成Form Kit主要由以下模块构成FormExtensionAbility卡片提供方必须继承的Ability用于管理卡片创建、更新、销毁。FormConfig.json配置文件声明卡片名称、尺寸、更新周期、支持端侧等。卡片UI页面ArkTS卡片对应一个Entry Component组件JS卡片对应index.hml等文件。FormManager系统统一管理卡片实例的服务负责分发事件、控制刷新。最简卡片声明与配置ArkTS下面不是完整项目只展示关键代码片段。假设你的应用包名为com.example.myform。1. 配置module.json5在对应entry的module.json5中{abilities:[{name:EntryFormAbility,srcEntry:./ets/entryability/EntryFormAbility.ts,formsEnabled:true,forms:[{name:WeatherForm,displayName:$string:weather_form_name,description:天气卡片,src:./ets/forms/WeatherCard.ets,window:{designWidth:100,autoDesignWidth:true},formConfigAbility:ability://com.example.myform.EntryFormAbility,updateEnabled:true,scheduledUpdateTime:10:30,updateDuration:1,defaultDimension:2*2,supportDimensions:[2*2,4*4]}]}]}关键字段说明formsEnabled必须设为true。srcEntryFormExtensionAbility的入口文件。forms数组每张卡片一个条目。src指向卡片UI组件。updateEnabled和updateDuration控制卡片自动更新时间分钟最小1分钟。2. FormExtensionAbility实现// EntryFormAbility.tsimport{FormExtensionAbility}fromkit.FormKit;import{Want}fromkit.AbilityKit;exportdefaultclassEntryFormAbilityextendsFormExtensionAbility{onCreate(want:Want){// 创建卡片时回调返回初始数据JSON对象return{temperature:25°C,city:上海};}onUpdate(formId:string){// 定时更新或主动调用时回调返回新数据return{temperature:26°C,city:上海};}onDestroy(formId:string){// 卡片被移除时清理资源console.info(Form${formId}destroyed);}}3. 卡片UI组件ArkTS// WeatherCard.etsEntryComponentstruct WeatherCard{LocalStorageProp(temperature)temperature:string;LocalStorageProp(city)city:string;build(){Column(){Text(this.city).fontSize(14).fontWeight(FontWeight.Bold)Text(this.temperature).fontSize(24).fontColor(Color.Orange)Button(刷新).onClick((){// 可调用updateForm接口主动刷新})}.width(100%).height(100%).padding(10).backgroundColor(Color.White)}}注意卡片UI组件不能使用State直接从本地更新必须通过LocalStorageProp从FormExtensionAbility返回的数据中读取。更新数据由系统通过onUpdate或updateForm接口推动。常见问题卡片生命周期与数据同步坑1卡片创建后UI不更新现象在onCreate中返回了数据但卡片显示空白或默认值。原因onCreate返回的数据需要与卡片的LocalStorageProp变量名一致。系统会把数据存入LocalStorage组件才能读取。如果组件中变量名写错数据自然丢失。解决方案确保返回的JSON键名与LocalStorageProp(key)的key完全匹配。建议在onCreate中打印日志确认数据格式。坑2定时更新不生效现象设置了updateDuration: 1分钟但卡片并未按1分钟刷新。原因系统对频繁更新有限制。updateDuration最小值为30分钟实际值为30如果你的值小于30系统会忽略并采用30分钟。文档未明确说明实测有效。解决方案如需更细粒度的刷新建议使用formProvider.updateForm()主动触发或结合定时任务。被动定时刷新只能30分钟起步。最佳实践尽可能减少LocalStorageProp变量数量每个变量都会在更新时触发整个卡片重建变量过多会明显卡顿。推荐用单个JSON对象包裹所有数据。避免在卡片UI中使用复杂动画卡片布局引擎限制动画时长和类型建议只使用基础显隐或透明度变化。及时释放onDestroy中的资源卡片实例数量有限如果删除卡片后未能清理订阅或定时器会导致内存泄漏。在onDestroy中取消所有事件监听。FAQQ为什么我的卡片在模拟器上能打开但真机桌面没显示A模拟器桌面可能不完整。真机上需要确认module.json5中formsEnable为true且卡片配置了supportDimensions。另外负一屏卡片需要额外配置formConfigAbility。Q卡片支持点击跳转吗A支持。在卡片UI中使用Button或Text绑定onClick事件跳转其他Ability需通过common.UIAbilityContext.startAbility但需要先获取卡片宿主Context不能直接使用当前AbilityContext。QJS卡片还能继续用吗A可以但官方不再增加新特性。API 12以后的新项目推荐全部迁移至ArkTS卡片。示例代码地址项目地址以上内容基于HarmonyOS NEXT API 12及以上版本具体行为请以真机运行结果为准。