HarmonyOS 多设备开发实践我把 SysCap、断点和折叠屏适配放到了同一套架构里HarmonyOS 多设备开发实践HarmonyOS 多设备开发实践我把 SysCap、断点和折叠屏适配放到了同一套架构里一、为什么要做鸿蒙原生二、第一个坑不要判断设备要判断能力三、第二个坑窗口才是不变的锚点四、第三层状态连续比布局适配更容易被忽略五、最终架构长什么样六、几个关键代码片段七、实际效果和一点感想一、为什么要做鸿蒙原生去年下半年我把之前用 React Pixi.js 写的一个消除小游戏《叠叠消》搬到了鸿蒙 NEXT 上。说实话一开始我觉得这事不复杂。游戏逻辑是现成的ArkUI 声明式写 UI 和 React 差别也没那么大Canvas 渲染路径也有现成的方案。最大的挑战无非就是适配——手机、折叠屏、平板三种屏幕响应式布局搞定对吧等真正上手写了两个月我才发现自己想简单了。问题从来不在 UI 怎么画而在于你用什么维度来判断当前是什么环境设备类型窗口宽度还是能力每一项选错了后面就是一串 if-else 补丁。这篇文章就把我在这条路上踩过的坑和最终的架构方案梳理一下。二、第一个坑不要判断设备要判断能力我一开始的写法和大多数人一样if(isPhone){// 显示扫码入口}后来上了折叠屏加了isFoldable。又考虑平板加了isTablet。再后来鸿蒙设备越来越多——折叠屏还有折叠态和展开态每个态的设备特征还不一样。if-else 越堆越多每次新设备发版我都要改一遍代码。这个问题的根源在于我们在用设备类型去代理本该由能力来决定的事情。HarmonyOS 提供了一套叫 SysCapSystem Capability的机制核心就是一个 API——canIUse()。// 不需要判断是不是手机// 直接问有没有摄像头if(canIUse(SystemCapability.Multimedia.Camera)){// 显示扫码入口}我在项目里遇到三个真实场景Camera 扫码。游戏里有个扫码兑换礼包的功能折叠屏在折叠态下摄像头位置变了但这不是代码该关心的事。canIUse(Camera)返回 true入口就亮返回 false 就隐藏。SoftBus 附近联机。鸿蒙的分布式软总线可以实现附近设备联机对战但不是所有设备都支持。用 SysCap 检测一下支持就显示联机入口不支持就隐藏。NFC 碰一碰。同理有没有 NFC 能力一查便知。这套逻辑想通之后我删掉了项目里所有isPhone、isFoldable、isTablet之类的判断。代码量没少多少但心理负担少了一大半——以后出什么新设备都不需要改我这层代码了。三、第二个坑窗口才是不变的锚点如果说 SysCap 解决的是有没有能力的问题那布局适配解决的是屏幕有多大的问题。官方文档反复强调一句话页面适配本质上是窗口适配。我当时没太当回事直到在折叠屏上翻了车。我一开始的做法是监听display.on(foldStatusChange)展开时切双列布局折叠时切单列布局。看起来挺合理的直到我遇到了三个场景分屏模式窗口宽度缩到一半foldStatus 没变布局没反应悬浮窗窗口变成小方块foldStatus 还是展开态内容全挤在一起外接显示器根本不是折叠屏更不会触发foldStatusChange告诉我的是设备的物理形态变了而布局适配需要知道的是当前窗口给我留了多少空间。这是两件完全不同的事。后来改成了这套链路Window → Breakpoint → Layout核心就是监听windowSizeChange然后通过断点Breakpoint映射到布局// 监听窗口变化display.on(windowSizeChange,(size:window.Size){constbreakpointgetBreakpoint(size.width);AppStorage.Set(breakpoint,breakpoint);});// 断点映射functiongetBreakpoint(width:number):string{if(width520)returnsm;if(width840)returnmd;returnlg;}断点信息通过AppStorage全局广播所有页面自动刷新布局。具体的布局逻辑交给了LayoutManager游戏引擎本身完全不知道外面是手机还是折叠屏。以《叠叠消》为例手机竖屏~360vp是上下结构┌──────────┐ │ Board │ │ 图案堆区 │ ├──────────┤ │ Slot │ │ 收集槽 │ └──────────┘折叠屏展开~800vp变成左右结构┌──────────┬──────────┐ │ │ Tool │ │ Board │ 道具栏 │ │ 图案堆 ├──────────┤ │ │ Slot │ │ │ 收集槽 │ └──────────┴──────────┘GameEngine 只处理消除逻辑不需要知道外面是哪种布局。LayoutManager 拿到断点后决定排布方式丢到 GridRow/GridCol 里就行。分屏、悬浮窗、PC 大屏全部走同一套逻辑不需要单独处理。四、第三层状态连续比布局适配更容易被忽略UI 适配做完了但还有一个问题用户手机玩一半换平板登录进度能续上吗多设备开发如果只适配了屏幕没适配状态用户感知到的就不是多端无缝而是换个设备从头再来。这个项目的方案是用鸿蒙 CloudDB// CloudDB 监听云端变更cloudDB.on(snapshot,(snapshot:databases.Snapshot){if(snapshot.eventTypedatabases.EventType.MONITOR_SNAPSHOT){// 云端数据变了合并到本地mergeProgress(snapshot.data);}});// 本地数据变更时写入云端functionsaveProgress(level:number,stars:number){preferences.put(level,level);preferences.put(stars,stars);cloudDB.executeUpsert(user_progress,{level,stars});}策略是本地优先写入云端冲突时以云端版本为准。实际体验下来换设备登录华为账号后5 秒内进度完全恢复。少写一个后端服务而且天然支持多设备同步。如果自己搭服务器做进度同步光是联调测试就要花不少时间。五、最终架构长什么样把前面三层的逻辑串起来最终的架构是这样的Device手机 / 折叠屏 / 平板 │ ┌────────┴────────┐ │ │ SysCap Window 能力检测 窗口状态 │ │ └──────┬───────────┘ │ Breakpoint sm / md / lg │ LayoutManager 布局决策 │ GameEngine 游戏逻辑——完全不变 │ GameState / ArkUI 渲染层每层的职责SysCap 层回答有没有能力——Camera、SoftBus、NFC 等与 UI 无关Window 层回答窗口多大——监听windowSizeChange不关心设备类型Breakpoint 层把窗口宽度映射为 sm/md/lg全局广播LayoutManager根据 breakpoint 决定布局方案GameEngine纯游戏逻辑对设备、窗口、布局一概不知这套架构跑通之后后面再增加新设备形态——比如鸿蒙车机、智慧屏——只需要在 LayoutManager 里加一组新的断点映射就行其他层完全不动。六、几个关键代码片段所有代码里真正核心的就这么几段能力检测// 动态检测——扫码入口要不要显示if(canIUse(SystemCapability.Multimedia.Camera)){// 显示扫码按钮}断点监听与全局广播constlistenermediaquery.matchMediaSync((min-width: 600vp));listener.on(change,(result:mediaquery.MediaQueryResult){constbpresult.matches?md:sm;AppStorage.Set(breakpoint,bp);});窗口变化驱动断点重算display.on(windowSizeChange,(size:window.Size){constbpsize.width520?sm:size.width840?md:lg;AppStorage.Set(breakpoint,bp);});ArkUI 属性动画收集槽图案归位// 收集槽相同图案自动聚合属性动画驱动位移animateTo({duration:150,curve:Curve.FastOutSlowIn},(){this.slotPositionscomputeAggregatedPositions(this.slots);});ArkUI 的animateTo直接对状态变量做补间不用操作 DOM 元素。对于收集槽频繁的位移动画来说这比手动算 transform 省心多了。七、实际效果和一点感想项目最终跑起来的效果手机 ✓、折叠屏 ✓、平板 ✓窗口缩放适配 ✓状态跨设备连续 ✓能力动态适配 ✓包体 28MB冷启动 1.8s游戏页稳定 60fps做这个项目之前我以为多设备开发最大的工作量是 UI 适配。做下来发现UI 适配反而是最后一步。真正决定代码能不能维护下去的是前期有没有把SysCap能力层、Breakpoint窗口层和状态连续放进同一套架构里想清楚。现在回头看那个用if (isPhone)开头的版本其实不是在适配设备是在逃避思考。设备是无限的窗口是有规律的能力才是真正需要关心的。想明白这三层的关系后面加什么设备都不慌。你的项目里真的需要判断设备类型吗参考资料HarmonyOS 开发文档 - SysCapHarmonyOS 开发文档 - 多设备布局HarmonyOS 开发文档 - CloudDB
HarmonyOS 多设备开发实践我把 SysCap、断点和折叠屏适配放到了同一套架构里HarmonyOS 多设备开发实践HarmonyOS 多设备开发实践我把 SysCap、断点和折叠屏适配放到了同一套架构里一、为什么要做鸿蒙原生二、第一个坑不要判断设备要判断能力三、第二个坑窗口才是不变的锚点四、第三层状态连续比布局适配更容易被忽略五、最终架构长什么样六、几个关键代码片段七、实际效果和一点感想一、为什么要做鸿蒙原生去年下半年我把之前用 React Pixi.js 写的一个消除小游戏《叠叠消》搬到了鸿蒙 NEXT 上。说实话一开始我觉得这事不复杂。游戏逻辑是现成的ArkUI 声明式写 UI 和 React 差别也没那么大Canvas 渲染路径也有现成的方案。最大的挑战无非就是适配——手机、折叠屏、平板三种屏幕响应式布局搞定对吧等真正上手写了两个月我才发现自己想简单了。问题从来不在 UI 怎么画而在于你用什么维度来判断当前是什么环境设备类型窗口宽度还是能力每一项选错了后面就是一串 if-else 补丁。这篇文章就把我在这条路上踩过的坑和最终的架构方案梳理一下。二、第一个坑不要判断设备要判断能力我一开始的写法和大多数人一样if(isPhone){// 显示扫码入口}后来上了折叠屏加了isFoldable。又考虑平板加了isTablet。再后来鸿蒙设备越来越多——折叠屏还有折叠态和展开态每个态的设备特征还不一样。if-else 越堆越多每次新设备发版我都要改一遍代码。这个问题的根源在于我们在用设备类型去代理本该由能力来决定的事情。HarmonyOS 提供了一套叫 SysCapSystem Capability的机制核心就是一个 API——canIUse()。// 不需要判断是不是手机// 直接问有没有摄像头if(canIUse(SystemCapability.Multimedia.Camera)){// 显示扫码入口}我在项目里遇到三个真实场景Camera 扫码。游戏里有个扫码兑换礼包的功能折叠屏在折叠态下摄像头位置变了但这不是代码该关心的事。canIUse(Camera)返回 true入口就亮返回 false 就隐藏。SoftBus 附近联机。鸿蒙的分布式软总线可以实现附近设备联机对战但不是所有设备都支持。用 SysCap 检测一下支持就显示联机入口不支持就隐藏。NFC 碰一碰。同理有没有 NFC 能力一查便知。这套逻辑想通之后我删掉了项目里所有isPhone、isFoldable、isTablet之类的判断。代码量没少多少但心理负担少了一大半——以后出什么新设备都不需要改我这层代码了。三、第二个坑窗口才是不变的锚点如果说 SysCap 解决的是有没有能力的问题那布局适配解决的是屏幕有多大的问题。官方文档反复强调一句话页面适配本质上是窗口适配。我当时没太当回事直到在折叠屏上翻了车。我一开始的做法是监听display.on(foldStatusChange)展开时切双列布局折叠时切单列布局。看起来挺合理的直到我遇到了三个场景分屏模式窗口宽度缩到一半foldStatus 没变布局没反应悬浮窗窗口变成小方块foldStatus 还是展开态内容全挤在一起外接显示器根本不是折叠屏更不会触发foldStatusChange告诉我的是设备的物理形态变了而布局适配需要知道的是当前窗口给我留了多少空间。这是两件完全不同的事。后来改成了这套链路Window → Breakpoint → Layout核心就是监听windowSizeChange然后通过断点Breakpoint映射到布局// 监听窗口变化display.on(windowSizeChange,(size:window.Size){constbreakpointgetBreakpoint(size.width);AppStorage.Set(breakpoint,breakpoint);});// 断点映射functiongetBreakpoint(width:number):string{if(width520)returnsm;if(width840)returnmd;returnlg;}断点信息通过AppStorage全局广播所有页面自动刷新布局。具体的布局逻辑交给了LayoutManager游戏引擎本身完全不知道外面是手机还是折叠屏。以《叠叠消》为例手机竖屏~360vp是上下结构┌──────────┐ │ Board │ │ 图案堆区 │ ├──────────┤ │ Slot │ │ 收集槽 │ └──────────┘折叠屏展开~800vp变成左右结构┌──────────┬──────────┐ │ │ Tool │ │ Board │ 道具栏 │ │ 图案堆 ├──────────┤ │ │ Slot │ │ │ 收集槽 │ └──────────┴──────────┘GameEngine 只处理消除逻辑不需要知道外面是哪种布局。LayoutManager 拿到断点后决定排布方式丢到 GridRow/GridCol 里就行。分屏、悬浮窗、PC 大屏全部走同一套逻辑不需要单独处理。四、第三层状态连续比布局适配更容易被忽略UI 适配做完了但还有一个问题用户手机玩一半换平板登录进度能续上吗多设备开发如果只适配了屏幕没适配状态用户感知到的就不是多端无缝而是换个设备从头再来。这个项目的方案是用鸿蒙 CloudDB// CloudDB 监听云端变更cloudDB.on(snapshot,(snapshot:databases.Snapshot){if(snapshot.eventTypedatabases.EventType.MONITOR_SNAPSHOT){// 云端数据变了合并到本地mergeProgress(snapshot.data);}});// 本地数据变更时写入云端functionsaveProgress(level:number,stars:number){preferences.put(level,level);preferences.put(stars,stars);cloudDB.executeUpsert(user_progress,{level,stars});}策略是本地优先写入云端冲突时以云端版本为准。实际体验下来换设备登录华为账号后5 秒内进度完全恢复。少写一个后端服务而且天然支持多设备同步。如果自己搭服务器做进度同步光是联调测试就要花不少时间。五、最终架构长什么样把前面三层的逻辑串起来最终的架构是这样的Device手机 / 折叠屏 / 平板 │ ┌────────┴────────┐ │ │ SysCap Window 能力检测 窗口状态 │ │ └──────┬───────────┘ │ Breakpoint sm / md / lg │ LayoutManager 布局决策 │ GameEngine 游戏逻辑——完全不变 │ GameState / ArkUI 渲染层每层的职责SysCap 层回答有没有能力——Camera、SoftBus、NFC 等与 UI 无关Window 层回答窗口多大——监听windowSizeChange不关心设备类型Breakpoint 层把窗口宽度映射为 sm/md/lg全局广播LayoutManager根据 breakpoint 决定布局方案GameEngine纯游戏逻辑对设备、窗口、布局一概不知这套架构跑通之后后面再增加新设备形态——比如鸿蒙车机、智慧屏——只需要在 LayoutManager 里加一组新的断点映射就行其他层完全不动。六、几个关键代码片段所有代码里真正核心的就这么几段能力检测// 动态检测——扫码入口要不要显示if(canIUse(SystemCapability.Multimedia.Camera)){// 显示扫码按钮}断点监听与全局广播constlistenermediaquery.matchMediaSync((min-width: 600vp));listener.on(change,(result:mediaquery.MediaQueryResult){constbpresult.matches?md:sm;AppStorage.Set(breakpoint,bp);});窗口变化驱动断点重算display.on(windowSizeChange,(size:window.Size){constbpsize.width520?sm:size.width840?md:lg;AppStorage.Set(breakpoint,bp);});ArkUI 属性动画收集槽图案归位// 收集槽相同图案自动聚合属性动画驱动位移animateTo({duration:150,curve:Curve.FastOutSlowIn},(){this.slotPositionscomputeAggregatedPositions(this.slots);});ArkUI 的animateTo直接对状态变量做补间不用操作 DOM 元素。对于收集槽频繁的位移动画来说这比手动算 transform 省心多了。七、实际效果和一点感想项目最终跑起来的效果手机 ✓、折叠屏 ✓、平板 ✓窗口缩放适配 ✓状态跨设备连续 ✓能力动态适配 ✓包体 28MB冷启动 1.8s游戏页稳定 60fps做这个项目之前我以为多设备开发最大的工作量是 UI 适配。做下来发现UI 适配反而是最后一步。真正决定代码能不能维护下去的是前期有没有把SysCap能力层、Breakpoint窗口层和状态连续放进同一套架构里想清楚。现在回头看那个用if (isPhone)开头的版本其实不是在适配设备是在逃避思考。设备是无限的窗口是有规律的能力才是真正需要关心的。想明白这三层的关系后面加什么设备都不慌。你的项目里真的需要判断设备类型吗参考资料HarmonyOS 开发文档 - SysCapHarmonyOS 开发文档 - 多设备布局HarmonyOS 开发文档 - CloudDB
