HarmonyOS 小游戏《对战五子棋》开发第39篇 - 最佳实践与注意事项

避坑指南——鸿蒙游戏开发中必须注意的那些事一、ArkTS语言注意事项1. 不支持内联对象类型// ❌ 报错constitems:{row:number,col:number}[][];// ✅ 正确exportclassMove{row:number;col:number;constructor(row:number,col:number){this.rowrow;this.colcol;}}constitems:Move[][];2. Prop数组需要新引用触发Watch// ❌ 修改原数组不触发Watchthis.boardData[0]BLACK;// ✅ 创建新数组触发Watchthis.boardDatathis.engine.toFlatArray();3. 回调函数属性需要默认值// ❌ 缺少默认值onCellClick:(row:number,col:number)void;// ✅ 提供默认空函数onCellClick:(row:number,col:number)void(){};4. 所有类型必须显式标注// ❌ 依赖类型推断letcount0;// ✅ 显式标注letcount:number0;二、Canvas绘制注意事项1. onReady前不能绘制privateisReady:booleanfalse;.onReady((){this.isReadytrue;// 标记就绪this.drawBoard();})onDataChange():void{if(this.isReady){// 检查就绪this.drawBoard();}}2. 每次绘制必须clearRect// 不清空会导致画面叠加ctx.clearRect(0,0,size,size);// 然后重新绘制3. 尺寸通过onAreaChange获取.onAreaChange((_oldValue:Area,newValue:Area){constwnewValue.width;if(typeofwnumber){this.canvasSizew;}})4. 防御性检查if(size0)return;// 防止尺寸为0时绘制三、状态管理注意事项1. State vs Prop vs LinkState组件内部状态可变 Prop父→子单向传递只读副本 Link父↔子双向绑定引用同步2. StorageLink持久化// 自动持久化跨页面共享StorageLink(key)value:number0;3. 条件渲染会销毁组件if(this.showDialog){CustomComponent()// false时完全销毁true时重新创建}四、性能优化注意事项1. ForEach必须提供keyGeneratorForEach(data,(item){...},(item)item.id.toString())// ↑ 必须提供2. 避免在build()中做复杂计算// ❌ 每次重绘都计算build(){Text(this.expensiveCompute())}// ✅ 缓存计算结果privatecachedText:string;aboutToAppear(){this.cachedTextthis.expensiveCompute();}build(){Text(this.cachedText)}3. Canvas全量重绘够用15x15棋盘全量重绘约260次Canvas操作1-3ms完成。不需要增量更新。4. AI计算放在setTimeout中// 避免阻塞UI线程this.aiThinkingtrue;setTimeout((){this.makeAIMove();// AI计算在下一个事件循环},400);五、路由导航注意事项1. 页面必须注册// main_pages.json { src: [pages/Index, pages/TwoPlayerPage] }未注册的页面router.pushUrl会报错。2. 返回逻辑要考虑页面状态// AIBattlePage的返回按钮if(this.inGame){this.backToLevelSelect();// 游戏中→返回选关}else{router.back();// 选关→返回首页}3. 清理定时器aboutToDisappear():void{if(this.aiTimerId!-1){clearTimeout(this.aiTimerId);}}六、资源管理注意事项1. 颜色资源化// ❌ 硬编码.backgroundColor(#4A90D9)// ✅ 资源引用支持深色模式.backgroundColor($r(app.color.button_primary))2. 深色模式适配// dark/element/color.json{name:bg,value:#333333}3. 字符串国际化// zh_CN: { name: app_name, value: 五子棋 }// en_US: { name: app_name, value: Gomoku }七、调试技巧1. 统一日志前缀console.info([Gomoku] some message);// 方便过滤2. Previewer实时预览不需要启动模拟器快速查看UI效果。3. hdc日志查看hdc hilog|grepGomoku总结HarmonyOS游戏开发的核心注意事项ArkTS限制无内联类型、类型必须显式Canvas生命周期onReady后才绘制Prop数组需要新引用触发WatchForEach必须提供keyGenerator定时器清理aboutToDisappear中clearTimeout页面注册main_pages.json中注册所有页面资源化颜色/字符串用资源引用掌握这些注意事项能避免90%的常见问题。