原子服务卡片是鸿蒙系统最具辨识度的特色能力之一不用打开应用在桌面就能直接查看核心信息、执行快捷操作是提升应用触达率的重要入口。鸿蒙 7API 26进一步增强了卡片的互动能力与动效表现支持深色模式自动适配、摇一摇动态特效、内联点击事件开发规范也全面对齐 kit 套件体系。本文带你从零开发一个待办统计服务卡片完整支持 2×2中号、2×4大号两种主流尺寸包含卡片生命周期、数据绑定、交互事件、主动更新全流程所有代码可直接复制运行全程基于 API 26 官方标准规范。一、先搞懂原子服务卡片核心基础1.1 什么是原子服务卡片原子服务卡片Widget是嵌入在鸿蒙桌面的微型应用页面无需启动主应用即可展示信息、执行轻量操作。它和主应用共用一套 ArkUI 技术栈底层共享沙箱数据开发成本极低。鸿蒙桌面以「格」为单位主流支持四种标准尺寸尺寸规格形态说明适用场景1×2窄条形1格宽2格高单条信息、快捷开关2×2正方形2格宽2格高数据统计、快捷入口2×4竖长方形2格宽4格高列表信息、多操作入口4×4大正方形4格宽4格高大屏展示、丰富交互1.2 鸿蒙 7 卡片核心升级互动能力增强新增onFormEvent回调卡片内按钮点击可直接触发数据更新无需跳转主应用动效原生支持接入沉浸光感、摇一摇动态特效和系统卡片质感统一kit 规范对齐全面纳入kit.AbilityKit体系替代旧版零散的ohos.app.form接口深色模式自动适配跟随系统深浅色自动切换无需手动编写两套样式1.3 开发前置条件SDK 版本API 26HarmonyOS NEXT 7.0及以上开发工具DevEco Studio 5.0 及以上工程模型Stage 模型FA 模型已淘汰不支持新版卡片能力核心依赖kit.AbilityKit卡片生命周期与数据绑定、kit.ArkUI卡片UI渲染二、第一步工程配置与清单声明卡片开发的第一步是在模块配置文件中声明卡片能力这是新手最容易踩坑的环节配置错误会导致桌面找不到卡片。2.1 基础工程准备先创建一个标准的 Stage 模型 ArkTS 工程确认根目录build-profile.json5编译版本符合要求{ app: { compileSdkVersion: 26.0.0, compatibleSdkVersion: 26.0.0, targets: [{ name: default, runtimeOS: HarmonyOS }] } }2.2 module.json5 卡片配置打开entry/src/main/module.json5在extensionAbilities数组中添加卡片扩展能力配置。这是卡片的「身份证」系统通过它识别你的应用支持卡片。完整配置如下关键项已加注释extensionAbilities: [ { name: TodoFormAbility, srcEntry: ./ets/form/TodoFormAbility.ets, description: $string:form_desc, type: form, icon: $media:icon, label: $string:form_label, formsEnabled: true, forms: [ { name: TodoCard, displayName: $string:form_display_name, description: $string:form_desc, src: ./ets/widget/TodoCard.ets, uiSyntax: arkts, window: { designWidth: 720, autoDesignWidth: false }, colorMode: auto, formVisibleNotify: true, isDefault: true, updateEnabled: true, updateDuration: 30, defaultDimension: 2*2, supportDimensions: [2*2, 2*4] } ] } ]关键配置说明type: form声明这是一个服务卡片扩展必须准确填写srcEntry卡片生命周期处理类的文件路径forms.src卡片 UI 页面的 ArkTS 文件路径supportDimensions声明支持的所有尺寸用户添加卡片时可选择defaultDimension卡片默认尺寸updateDuration自动更新周期单位为分钟最小 30 分钟colorMode: auto自动跟随系统深浅色模式三、第二步编写卡片生命周期处理类卡片有独立的生命周期由FormExtensionAbility统一管理负责卡片创建、更新、事件响应、销毁等逻辑。新建entry/src/main/ets/form/TodoFormAbility.ets完整代码如下import{FormExtensionAbility,formBindingData}fromkit.AbilityKit;import{hilog}fromkit.PerformanceAnalysisKit;constTAGTodoFormAbility;exportdefaultclassTodoFormAbilityextendsFormExtensionAbility{/** * 卡片首次被添加到桌面时触发 * 初始化卡片数据 */onCreate(formId:string):void{hilog.info(0x0000,TAG,卡片创建ID:${formId});constinitDatathis.buildCardData();// 绑定初始数据到卡片formBindingData.createFormBindingData(initData);}/** * 卡片更新时触发定时更新、主动调用更新 */onUpdate(formId:string):void{hilog.info(0x0000,TAG,卡片更新ID:${formId});constnewDatathis.buildCardData();// 主动更新卡片数据formBindingData.updateForm(formId,newData);}/** * 鸿蒙7新增处理卡片内的交互事件 * 点击卡片内按钮时触发无需跳转主应用 */onFormEvent(formId:string,message:string):void{hilog.info(0x0000,TAG,收到卡片事件:${message});if(messagerefresh){// 点击刷新按钮重新加载数据this.onUpdate(formId);}}/** * 卡片被从桌面移除时触发 */onDestroy(formId:string):void{hilog.info(0x0000,TAG,卡片销毁ID:${formId});}/** * 构造卡片数据模拟业务数据 * 实际项目中可从本地存储、数据库读取 */privatebuildCardData():Recordstring,Object{return{totalCount:6,doneCount:2,progress:33,todoList:[完成PersistenceV2教程,开发服务卡片,适配多尺寸,测试交互事件]};}}核心说明所有卡片能力统一从kit.AbilityKit导入符合新版 kit 开发规范formBindingData是数据绑定核心负责把业务数据和卡片 UI 字段关联onFormEvent是鸿蒙 7 互动卡片的核心卡片内点击事件直接回调到这里实现免启动应用刷新数据四、第三步卡片 UI 开发 多尺寸适配卡片 UI 和普通 ArkUI 页面写法基本一致但有两个核心差异数据通过Prop接收由系统自动注入绑定系统会自动注入formWidth/formHeight两个变量用于判断当前尺寸实现多尺寸适配4.1 多尺寸适配核心思路通过系统注入的宽高变量判断当前卡片规格使用条件渲染展示不同布局2×2 中号卡片简洁展示统计数据与进度突出核心信息2×4 大号卡片额外展示待办列表与操作按钮信息更丰富4.2 完整卡片 UI 代码新建entry/src/main/ets/widget/TodoCard.ets完整可运行代码如下Componentexportdefaultstruct TodoCard{// 系统自动注入卡片当前宽高单位vp用于多尺寸判断StateformWidth:number0;StateformHeight:number0;// 数据绑定与FormAbility中传入的key一一对应系统自动赋值ProptotalCount:number0;PropdoneCount:number0;Propprogress:number0;ProptodoList:string[][];/** * 判断是否为2×4大号卡片 * 高度大于400vp判定为大号 */getisLargeSize():boolean{returnthis.formHeight400;}/** * 发送刷新事件给FormAbility */handleRefresh(){postCardAction(this,{action:event,params:{message:refresh}});}/** * 点击卡片整体跳转主应用 */handleJumpApp(){postCardAction(this,{action:router,params:{uri:pages/Index}});}build(){Column({space:12}){// 顶部标题栏两种尺寸都显示Row(){Text(待办清单).fontSize(16).fontWeight(FontWeight.Medium).layoutWeight(1);if(this.isLargeSize){Text(刷新).fontSize(13).fontColor(#0A59F7).onClick(()this.handleRefresh());}}.width(100%);// 统计数字区两种尺寸都显示Row({space:8}){Text(${this.doneCount}).fontSize(28).fontWeight(FontWeight.Bold).fontColor(#0A59F7);Text(/${this.totalCount}).fontSize(14).fontColor(#888888).margin({top:8});}.width(100%);// 进度条Progress({value:this.progress,total:100,type:ProgressType.Linear}).width(100%).height(6).color(#0A59F7).backgroundColor(#E5E7EB);// 仅大号卡片显示待办列表if(this.isLargeSize){Column({space:8}){ForEach(this.todoList.slice(0,3),(item:string,index:number){Row({space:8}){Text(indexthis.doneCount?✓:).width(16).height(16).borderRadius(8).backgroundColor(indexthis.doneCount?#00B578:#FFFFFF).border({width:1.5,color:#DDDDDD}).fontSize(10).fontColor(#FFFFFF).textAlign(TextAlign.Center);Text(item).fontSize(14).fontColor(indexthis.doneCount?#999999:#333333).decoration({type:indexthis.doneCount?TextDecorationType.LineThrough:TextDecorationType.None}).layoutWeight(1).maxLines(1).textOverflow({overflow:TextOverflow.Ellipsis});}.width(100%);})}.width(100%).margin({top:4});}}.width(100%).height(100%).padding(16).backgroundColor(#FFFFFF).borderRadius(16).onClick(()this.handleJumpApp());}}代码核心说明自动注入变量formWidth、formHeight由系统自动赋值无需手动传参是多尺寸适配的核心依据数据自动绑定Prop变量名和formBindingData中的 key 一一对应数据变化自动刷新 UI事件交互postCardAction是卡片专用交互方法支持event发送事件和router跳转应用两种动作条件渲染适配通过isLargeSize计算属性控制列表显隐不同尺寸展示不同粒度的信息五、主应用内主动更新卡片除了定时自动更新主应用内数据变化时也可以主动触发所有卡片刷新。在主页面Index.ets中添加更新按钮调用更新接口import{formBindingData,formInfo}fromkit.AbilityKit;import{promptAction}fromkit.ArkUI;// 主动更新所有待办卡片asyncupdateAllCards(){try{// 获取当前应用所有已添加的卡片IDconstformIdsawaitformInfo.getFormIds();if(formIds.length0){promptAction.showToast({message:暂无已添加的卡片});return;}// 构造新数据constnewData{totalCount:8,doneCount:5,progress:62,todoList:[新任务1,新任务2,新任务3,新任务4]};// 批量更新所有卡片formIds.forEach(formId{formBindingData.updateForm(formId,newData);});promptAction.showToast({message:已更新${formIds.length}张卡片});}catch(err){promptAction.showToast({message:更新失败});}}六、运行验证步骤将工程编译运行到模拟器或真机安装主应用回到桌面双指向内捏合进入桌面编辑模式点击「服务卡片」在应用列表中找到你的应用即可看到支持的两种尺寸卡片分别拖拽 2×2 和 2×4 尺寸到桌面验证布局差异点击大号卡片的「刷新」按钮验证互动更新是否生效打开主应用点击更新按钮验证主动刷新是否生效七、新手高频踩坑与解决方案1. 桌面找不到服务卡片原因module.json5配置错误最常见是type没写form、文件路径写错、formsEnabled为 false解决对照本文配置逐项核对确保srcEntry和forms.src的路径与实际文件位置完全一致2. 卡片显示「加载失败」占位图原因卡片 UI 代码有语法错误或使用了卡片不支持的组件如 TextInput、Scroll 等解决检查 HiLog 报错日志卡片优先使用基础展示组件复杂交互建议跳转主应用实现3. 多尺寸不生效只有一种尺寸原因supportDimensions配置格式错误或尺寸判断逻辑阈值不合理解决尺寸格式必须为2*2星号不是×宽高阈值根据设备实际 vp 调整建议用区间判断而非固定值4. 卡片数据不更新原因Prop变量名和数据 key 不匹配或updateForm传入的 formId 错误解决确保变量名与数据 key 完全一致打印日志确认 formId 正确有效5. 导入 FormExtensionAbility 报错原因SDK 版本低于 API 12或使用旧版ohos.app.form导入解决升级 SDK 到 26.0.0 及以上统一从kit.AbilityKit导入相关能力八、总结原子服务卡片开发的核心可以概括为「一份配置 一个生命周期类 一套自适应UI」配置是入口决定卡片有哪些尺寸、叫什么名字生命周期类是中枢负责数据供给与事件处理UI 层通过系统注入的宽高实现多尺寸适配一套代码覆盖多种规格对于新手建议先实现 2×2 基础尺寸跑通全流程再扩展大号尺寸与互动能力鸿蒙 7 的互动卡片能力可以实现很多轻量操作不用跳转应用就能完成刷新、切换等动作大幅提升用户体验。