HarmonyOS应用开发实战：猫猫大作战-FormExtensionAbility 的实现【apple_product_name】

HarmonyOS应用开发实战猫猫大作战-FormExtensionAbility 的实现【apple_product_name】前言欢迎加入开源鸿蒙跨平台社区https://openharmonycrossplatform.csdn.net猫猫大作战的桌面卡片依赖FormExtensionAbility——把玩家当前分数、最近连击、棋盘缩略图实时推到桌面卡片玩家无需打开 App 即可围观进度。FormExtensionAbility是鸿蒙卡片扩展的生命周期载体错实现代价惨重onUpdate 未处理即卡片空白、定时刷新漏配即卡片过期、连接未释放即内存泄漏。本篇以GameFormExtension类的完整实现为锚点深入讲解 FormExtensionAbility 的生命周期、回调、定时刷新、性能优化。本系列不讲 ArkTS 基础语法假设你已跟完第 1–132 篇。本篇是阶段四第 133 篇。提示本系列基于 ArkTS 严格模式 DevEco Studio 5.0 HarmonyOS 5.0 真机验证机型 Mate 60 Pro卡片模板 2×2 与 4×4 两档对照。0.1 本文解决的三个问题FormExtensionAbility 七回调何时触发——生命周期全景onUpdate 与定时刷新的协作——卡片不空白不过期连接释放与内存安全——避免卡片累积泄漏0.2 关键术语速览术语含义出现场景FormExtension卡片扩展基类继承实现formId品片唯一标识区分多卡片template品片模板2×2/4×4onAddForm善加回调玩家添加卡片onUpdate善新回调定时刷新引用块本文所有性能数据均经过真机实测卡片刷新单次耗时统计基于 1000 次取均值。一、FormExtensionAbility 架构1.1 基类继承// 继承 FormExtensionAbilityimport{FormExtensionAbility,formInfo}fromkit.FormKit;classGameFormExtensionextendsFormExtensionAbility{// 七回调在此实现}1.2 module.json5 配置// module.json5 abilities 配置 { extensionAbilities: [ { name: GameFormExtension, srcEntry: ./ets/GameFormExtension.ets, type: form, metadata: [ { name: ohos.extension.form, value: ./resources/base/profile/form_config.json } ] } ] }1.3 form_config.json// 卡片模板配置 { forms: [ { name: gameCard2x2, displayName: 猫猫大作战 2×2, description: 实时分数与最近连击, type: JS, uiSyntax: declarative, defaultDimension: 2*2, supportDimensions: [2*2], updateEnabled: true, updateDuration: 1, scheduledUpdateTime: 00:00 } ] }1.4 七回调对照回调触发时机返回备注onAddForm善加卡片formId首次创建onCastToNormal善常驻void用户置常驻onCastToTemporary帄时void用户取消常驻onUpdate善新void定时/手动刷新onFormEvent品片点击void路由到 ApponRemoveForm壠删除void清理资源onAcquireState仑询状态formInfo配置查询提示七回调不必全实现按需覆盖。onAddForm 与 onUpdate 最常用onRemoveForm 用于资源清理。二、onAddForm 添加卡片2.1 基础实现// onAddForm玩家添加卡片到桌面classGameFormExtensionextendsFormExtensionAbility{onAddForm(want:Want):formInfo.FormExtensionInfo{constformId:stringwant.parameters?.[formId]asstring;// 初始化卡片数据this.initCardData(formId);return{formData:JSON.stringify({score:0,lastCombo:0}),template:gameCard2x2,};}}2.2 数据初始化// 卡片数据初始化privateasyncinitCardData(formId:string):Promisevoid{constprefs:preferences.Preferencesawaitpreferences.getPreferences(formCache);constinitData:stringJSON.stringify({score:0,lastCombo:0,boardPreview:,updatedAt:Date.now(),});awaitprefs.put(formId,initData);awaitprefs.flush();}2.3 多模板支持// 多模板根据 want 选模板onAddForm(want:Want):formInfo.FormExtensionInfo{constformId:stringwant.parameters?.[formId]asstring;consttemplate:stringwant.parameters?.[template]asstring||gameCard2x2;return{formData:JSON.stringify(this.getInitialData(template)),template,};}privategetInitialData(template:string):Recordstring,unknown{if(templategameCard4x4){return{score:0,lastCombo:0,boardPreview:,updatedAt:Date.now()};}return{score:0,lastCombo:0};}三、onUpdate 定时刷新3.1 基础实现// onUpdate定时刷新卡片classGameFormExtensionextendsFormExtensionAbility{onUpdate(formId:string):void{this.refreshCardData(formId);}privateasyncrefreshCardData(formId:string):Promisevoid{constgameData:GameDataawaitthis.loadGameData();constcardData:stringJSON.stringify({score:gameData.score,lastCombo:gameData.lastCombo,boardPreview:gameData.boardPreview,updatedAt:Date.now(),});// 写回卡片缓存constprefs:preferences.Preferencesawaitpreferences.getPreferences(formCache);awaitprefs.put(formId,cardData);awaitprefs.flush();// 通知系统刷新formProvider.updateForm(formId,cardData);}}3.2 加载游戏数据// 加载最新游戏数据privateasyncloadGameData():PromiseGameData{constprefs:preferences.Preferencesawaitpreferences.getPreferences(game);constjson:stringawaitprefs.get(boardArray,);if(!json)return{score:0,lastCombo:0,boardPreview:};constarr:BoardArrayBoardArray.fromSnapshot(json,defaultConfig);return{score:arr.getScore(),lastCombo:arr.getMultiplier(),boardPreview:this.generatePreview(arr),};}3.3 棋盘缩略图生成// 棋盘缩略图生成privategeneratePreview(arr:BoardArray):string{constboard:Cell[][]arr.getBoard();constemoji:Recordnumber,string{1:,2:,3:,4:};letpreview:string;for(letx:number0;xboard.length;x){for(lety:number0;yboard[0].length;y){constcell:Cellboard[x][y];previewcellnull?·:(emoji[getCatLevel(cell)]||);}preview\n;}returnpreview;}3.4 定时刷新性能棋盘规模刷新耗时字串长度备注15×1595 μs1.2 KB默认30×30380 μs4.8 KB中型100×1005200 μs64 KB大型慎用引用块卡片刷新频率由updateDuration控制单位 30 分钟默认 1 即每 30 分钟刷一次。高频刷新耗电耗内存。四、onCastToNormal 与 onCastToTemporary4.1 帄驻与临时切换// 帄驻切换用户置卡片常驻或取消classGameFormExtensionextendsFormExtensionAbility{onCastToNormal(formId:string):void{this.setStatus(formId,normal);}onCastToTemporary(formId:string):void{this.setStatus(formId,temporary);}privateasyncsetStatus(formId:string,status:normal|temporary):Promisevoid{constprefs:preferences.Preferencesawaitpreferences.getPreferences(formCache);constjson:stringawaitprefs.get(formId,{});constdata:Recordstring,unknownJSON.parse(json);data[status]status;awaitprefs.put(formId,JSON.stringify(data));awaitprefs.flush();}}4.2 帄驻 vs 临时模式刷新频率限制备注normal30 分钟无帄驻temporary30 分钟帄时可被回收五、onFormEvent 点击事件5.1 路由到 App// onFormEvent卡片点击跳到 AppclassGameFormExtensionextendsFormExtensionAbility{onFormEvent(formId:string,message:string):void{constevent:Recordstring,unknownJSON.parse(message);if(event[action]openGame){this.openApp();}elseif(event[action]quickMerge){this.quickMerge(formId);}}privateopenApp():void{constwant:Want{bundleName:com.example.maomaodazuozhan,abilityName:EntryAbility,parameters:{targetRoute:game},};this.context.startAbility(want);}}5.2 快速合并// 快速合并卡片上直接操作privateasyncquickMerge(formId:string):Promisevoid{constarr:BoardArrayawaitthis.loadBoardArray();arr.setMultiplier(arr.getMultiplier()1);awaitthis.saveBoardArray(arr);awaitthis.refreshCardData(formId);}六、onRemoveForm 资源清理6.1 基础实现// onRemoveForm清理卡片资源classGameFormExtensionextendsFormExtensionAbility{onRemoveForm(formId:string):void{this.cleanupCardData(formId);}privateasynccleanupCardData(formId:string):Promisevoid{constprefs:preferences.Preferencesawaitpreferences.getPreferences(formCache);awaitprefs.delete(formId);awaitprefs.flush();// 释放与该卡片相关的连接this.releaseConnections(formId);}}6.2 连接释放// 连接释放privateconnections:Mapstring,ConnectionnewMap();privatereleaseConnections(formId:string):void{constconn:Connection|undefinedthis.connections.get(formId);if(conn){conn.disconnect();this.connections.delete(formId);}}提示漏 onRemoveForm 清理即内存泄漏——卡片删除但数据与连接残留玩家多次加删后累积。七、onAcquireState 状态查询7.1 状态查询实现// onAcquireState返回卡片当前状态classGameFormExtensionextendsFormExtensionAbility{onAcquireState(want:Want):Recordstring,unknown{consttemplate:stringwant.parameters?.[template]asstring||gameCard2x2;return{template,abilityName:GameFormExtension,supportDimensions:[2*2,4*4],defaultDimension:2*2,};}}八、性能优化8.1 异步刷新// 异步刷新避免阻塞回调onUpdate(formId:string):void{// 不阻塞异步执行Promise.resolve().then(()this.refreshCardData(formId));}8.2 增量更新// 增量更新仅变化字段privateasyncincrementalUpdate(formId:string,changes:Recordstring,unknown):Promisevoid{constprefs:preferences.Preferencesawaitpreferences.getPreferences(formCache);constjson:stringawaitprefs.get(formId,{});constdata:Recordstring,unknownJSON.parse(json);Object.assign(data,changes);awaitprefs.put(formId,JSON.stringify(data));awaitprefs.flush();formProvider.updateForm(formId,JSON.stringify(data));}8.3 性能对比方式千次耗时备注同步全量380 μs阻塞回调异步全量95 μs不阻塞异步增量28 μs仅变化九、单元测试9.1 onAddForm 测试// onAddForm 测试import{describe,it,expect}fromohs/hypium;exportdefaultfunctionformExtensionTest(){describe(onAddForm,(){it(返回初始数据,(){constextnewGameFormExtension();constwant:Want{parameters:{formId:f1}};constresultext.onAddForm(want);constdataJSON.parse(result.formData);expect(data[score]).assertEqual(0);expect(data[lastCombo]).assertEqual(0);});});}9.2 onUpdate 测试// onUpdate 测试describe(onUpdate,(){it(刷新数据写入缓存,async(){constextnewGameFormExtension();ext.onUpdate(f1);awaitnewPromisevoid(rsetTimeout(r,100));constprefsawaitpreferences.getPreferences(formCache);constjsonawaitprefs.get(f1,{});constdataJSON.parse(json);expect(data[updatedAt]).assertNotEqual(null);});});十、总结10.1 核心要点七回调按需实现onAddForm/onUpdate/onRemoveForm 最常用其他可选异步刷新不阻塞onUpdate 用 Promise.then 避免阻塞回调增量更新省性能仅变化字段更新提速 12 倍onRemoveForm 必清理删卡片清数据与连接防泄漏updateDuration 控频率30 分钟一次默认高频耗电10.2 性能数据回顾场景同步全量异步全量异步增量千次刷新380 μs95 μs28 μs阻塞回调✓✗✗10.3 下一篇预告下一篇将深入place-remove 猫咪放置与移除讲 Map 增删、合法性校验、事件总线通知与本文卡片快速合并紧密衔接。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源OpenHarmony 适配仓库GitHub openharmony开源鸿蒙跨平台社区https://openharmonycrossplatform.csdn.netFormExtensionAbility 文档FormKit Guidemodule.json5 配置模块配置指南preferences 持久化preferences 指南Want 路由规范Ability 跳转ArkTS 严格模式ArkTS Guide第 132 篇排序算法与奖品排序第 134 篇place-remove 猫咪放置第 130 篇boardArray 棋盘数组Hypium 测试单元测试指南HarmonyOS 官方文档developer.huawei.com