HarmonyOS 7 新特性12平行视界深潜——easy_go 两层配置字典、版本分层与六行窗口状态验证表文章目录HarmonyOS 7 新特性12平行视界深潜——easy_go 两层配置字典、版本分层与六行窗口状态验证表1、引言2、效果展示验证表的两端3、Kit 与 API两层配置与字段字典3.1 接入三步骤与两层结构3.2 字段字典十三项3.3 两个编译期互斥约束4、逻辑流5、实战六行验证表6、避坑6.1 配置平铺与互斥字段schema 校验失败的两种形态6.2 isEasySplit 读时机aboutToAppear 恒 false6.3 直板机 false 分支要显式处理而非忽略7、总结以及这次没测到的部分1、引言篇 5 用轻视界文集把平行视界的体验跑通跑了一遍分栏、点选同步、分割线拖拽、单窗退化。跑完之后配置层面的问题才真正浮出来——easy_go.json 里那两层结构每层管什么十三个选项字段哪些是 API 23 就有的、哪些是 26.0.0 才加的两套分栏选项router 与 navigation为什么不能共存以及最根本的一个问题配置写对了分栏就生效吗最后一个问题的答案是「不一定」而「不一定」的分布是有规律的。平行视界的生效条件由配置与设备窗口状态共同决定官方文档明说「无法仅靠静态配置预知」。所以这篇除了配置字典还给一张验证表六种窗口状态下 isEasySplit 的真机读数从直板机到分栏残留态逐行实测。字典告诉你怎么配验证表告诉你配了之后在哪些状态下会发生什么——两者合起来下一篇同类工程就不需要再踩一遍。环境声明HarmonyOS 7.0.0.107 (API 26) Release实测工程轻视界com.qingkouwei.lightview配置字典载体与 EasyGoProbecom.qingkouwei.easygoprobe状态验证载体DevEco Studio 26.0.0SDK 26.0.0.105 Release真机 Mate 60 ProALN-AL80麒麟 9000S直板机读数与 MatePad EdgeQXS-W00双模态分栏与窗口状态读数。读数全部真机实测。2、效果展示验证表的两端验证表的两端各放一张图。直板机端Mate 60 Pro 上诊断读数isEasySplit() false窗口宽 388vp、宽高比 0.46、density 3.25——几何距离 600vp 门槛差得远分栏在这类设备上不是「被关闭」而是「够不着」。分栏端MatePad Edge 平板形态下轻视界分栏生效左栏列表右栏正文1:1 分割。同一份 easy_go.json两台设备两种结局——配置没变变的是窗口状态这就是本篇要画的矩阵。3、Kit 与 API两层配置与字段字典3.1 接入三步骤与两层结构接入是纯配置驱动没有运行时调起接口profile 目录建 easy_go.json文件名自定、module.json5 加easyGo字段指向它、仅 entry 模块可配且应用级生效。配置文件两层第一层设备类型common全设备默认必配/phone/tablet可选配置后覆盖 common 在该类型的生效。官方在 tablet 的说明里夹了一句关键约束自由多窗模式下暂不支持平行视界——这句的位置本身是提示它挂在设备类型层但实际语义在窗口状态层验证表第六行会修正这个表述。第二层displayModeOptionswideWindowMode长方形宽屏窗口的显示方式≥600vp 且宽/高1.2/squareWindowMode方形宽屏窗口≥600vp 且两向比≤1.2/ 两套分栏选项。wideWindowMode 取值三选一routerSplit路由由 router 模块实现须配 routerSplitOptions/navigationSplit路由由 Navigation 组件实现须配 navigationSplitOptions/original关闭兼容运行行为。3.2 字段字典十三项两套 options 内通用的字段按版本分层列字段作用版本homePage主页Router 为页面路径Navigation 为 NavDestination name 或 navBar23relatedPage关联页必须有 homePage 才能配不支持传参23enableReducedContainerSize虚拟容器lpx/横向断点/窗口宽按右页尺寸算23fullScreenPages跳转即退出分栏的页数组不得与 home/related 重复23supportLandscapeFullscreen主动横屏时是否全屏默认 true23dialogSupportSplitDialog 是否分栏右半屏默认 true23wideSplit / squareSplit分栏比例与拖拽子字段 ratio、isDraggable26.0.0mode路由模式0 购物 / 1 导航默认 126.0.0pagePairs{from,to} 跳转关系对仅导航模式to 可配 *26.0.0transPages过渡页购物模式生效固定右显不支持右推左26.0.0splitDividerColor分割线颜色 light/dark#AARRGGBB26.0.0drawableRectHookdrawableRect 页面级容器能力默认 false26.0.0enableInSplitScreen窗口分屏场景进入平行视界默认 false26.0.0版本分层的工程含义API 23 的六个字段够跑通基础分栏本卷开源中国篇 10 与本篇篇 5 的最小配置只用了 homePage/relatedPage/wideSplit/mode 中前三者26.0.0 的八个增量解决的是「分栏之后怎么编排」——模式、关系对、过渡页、分割线样式、分屏嵌套。老配置在新 SDK 上继续有效增量字段全有默认值新配置回旧 SDK 则增量字段被忽略——分层使用的规矩是增量字段只做增强不做依赖核心分栏逻辑永远落在 23 字段上。3.3 两个编译期互斥约束约束一routerSplitOptions与navigationSplitOptions不能同时存在且混用 Router 与 Navigation 会导致部分行为异常——分栏的路由实现只能选一边。约束二schema 的 if/then 分支实证wideSplit.isDraggabletrue时ratio必须不出现开启拖拽后比例由系统三档吸附接管1:2/1:1/2:1篇 5 与开源中国篇 10 均实测。官方 schema 在 SDKdefault/hms/toolchains/modulecheck/easy_go.json拿不准直接对照。还有一个结构坑二层字段必须包在displayModeOptions里直接平铺 wideWindowMode 会 schema 校验失败——构建期报错信息不指字段名第一次撞会浪费一轮排查。4、逻辑流配置加载与分栏判定流phone/tablet 有专配无专配宽≥600vp 且比例达标不达标自由多窗管理态非管理态应用启动读 entry 模块 easyGo 配置设备类型匹配用专配覆盖 common用 common窗口几何判定窗口状态判定isEasySplitfalse 单页态分栏挂载 homePagerelatedPageisEasySplittrue运行时判定接口UIContext.isEasySplit()API 24 起是应用侧唯一的分栏感知口配套两个尺寸回调onRouterPageSizeChange()/onNavDestinationSizeChange()可见页尺寸变化时回调分栏拖拽与窗口缩放都会触发。判定有个读时机坑aboutToAppear 里读恒 false分栏尚未挂载须延迟到首帧后——篇 5 与开源中国篇 10 各踩一次本篇立为规矩。5、实战六行验证表#设备/窗口状态窗口几何isEasySplit来源1Mate 60 Pro 直板机全屏388vp宽/高 0.46density 3.25false本篇新测2MatePad Edge 平板形态分栏各 1418vp1:1true篇 5/开源中国篇 103MatePad Edge PC 形态 FULL_SCREEN分栏各 1418vptrue开源中国篇 154MatePad Edge PC 形态 FLOATING1100vp宽/高 1.50false开源中国篇 10 诊断5MatePad Edge PC 形态 MAXIMIZE1642vp宽/高 1.60false开源中国篇 10 诊断6FLOATING曾分栏后退回1418vp/栏true残留开源中国篇 15六行读出的三条规律。其一几何是必要非充分条件第 4/5 行几何全达标≥600vp 且比例1.2仍 false第 1 行几何不达标直接 false——几何门槛筛掉直板机窗口状态门槛筛掉自由多窗管理态两道筛子串联。其二官方「自由多窗暂不支持」的准确语义是窗口处于自由多窗管理态第 3 行 PC 形态全屏脱离管理态即 true设备形态只是管理态的常见载体不是依据本身。其三状态机不对称第 6 行进过分栏再退回浮窗分栏残留不释放——验证表要带历史列单看当前窗口状态解释不了这一行。验证表的使用规矩环境声明报整表不报单格。单格结论「某设备不支持平行视界」活不过一次状态切换矩阵只随新状态增行。本篇六行里有四行引自本卷前篇诊断读数——验证表天然是跨篇累积资产这也是深潜篇放在体验篇之后的原因体验篇产出读数深潜篇把读数组织成依据。三档吸附的补充读数篇 5isDraggabletrue 时分割线在 1:2/1:1/2:1 三档间吸附拖拽过程中窗口宽读数不变——分栏比例改的是两页分配不是窗口几何验证表的几何列因此在拖拽下稳定。六行状态之间的迁移关系画成图残留态的不对称边就一目了然几何不达标(直板机)几何达标非管理态进入自由多窗(FLOATING/MAXIMIZE)脱离管理态(FULL_SCREEN)退回浮窗(分栏不释放)状态机无出边(实测)窗口几何缩到门槛下单页态分栏态管理态单页残留分栏图里最值得盯的是「残留分栏」的自环它没有出边——实测中没有任何用户操作能让残留态退回单页态重启应用会重建窗口那是另一条路径。状态机的这条死边是系统行为应用侧的应对只有让位读到 true 就按分栏渲染不试图纠正。6、避坑6.1 配置平铺与互斥字段schema 校验失败的两种形态现象首版 easy_go.json 把 wideWindowMode 直接平铺在设备类型下构建报 schema 校验失败但不指字段第二版加了 isDraggable 又保留 ratio再次失败。根因二层字段须包在 displayModeOptions 包裹层wideSplit 的 isDraggable 与 ratio 是 schema if/then 互斥分支。最佳实践SDK 自带官方 schemamodulecheck/easy_go.json配置写完先对照再构建拖拽与固定比例二选一要拖拽就删 ratio。验证对照 schema 重写后构建通过三档吸附行为与官方描述一致。6.2 isEasySplit 读时机aboutToAppear 恒 false现象分栏态下首页按 aboutToAppear 的读数走了单页分支两栏内容叠罗汉。根因分栏挂载晚于页面创建创建瞬间读到的永远是 false。最佳实践延迟到首帧后读setTimeout 300ms 实测足够或用 onRouterPageSizeChange 回调驱动业务判定与实测读数都不在创建瞬间取。验证延迟读后分栏态分支正确本卷三个工程轻视界/户型台/速记台知识库同法复用零重踩。6.3 直板机 false 分支要显式处理而非忽略现象篇 5 首版只写了分栏与宽窗两个分支直板机上列表页渲染出 260vp 列表加挤成一条的内嵌正文。根因验证表第 1 行的状态几何不达标在开发机上不出现开发期全在平板/PC 形态调分支漏写直到手机装机才暴露。最佳实践单页态分支按「窄窗单栏」设计列表全宽、点选 push 整页与分栏态共用列表组件只换容器——漏分支的代价从「布局挤坏」降为「体验降级」。验证补分支后 Mate 60 Pro 上列表全宽可读push 导航正常。7、总结以及这次没测到的部分配置字典与验证表是这篇的两件产出字典解决「怎么配」十三字段按 23/26 分层、两套 options 互斥、包裹层与拖拽比例互斥三个硬要求列在明面验证表解决「配了之后会怎样」六行状态读数把官方的单句约束展开成可增行的矩阵。两者合起来的工程价值是一句话平行视界的配置是声明式的行为是状态相关的声明式配置的正确性只能靠状态矩阵验证。这次没测到的部分列在这里navigationSplit 路线Navigation 分栏未实测本篇全走 routerSplitnavigationSplitOptions 的额外字段navBar 首页语义放到下篇讲mode 0 购物模式与 pagePairs/transPages 未实测需多页关系对场景本篇 mode1 导航模式enableReducedContainerSize 虚拟容器的 lpx 换算差异未量化实测验证表第 6 行残留态的恢复条件何时释放未测应用侧只让位不纠正直板机横屏态宽屏几何可达但设备类型 phone未测验证表这一行还空着字典会随版本增字段矩阵会随状态增行——这篇的价值不在今天的十三字段与六行在「增字段查字典、增状态查矩阵」的工作方式。具体到操作面留三条配置改动后先过 schema 对照再过构建6.1 的两个互斥都是构建期才报对照 schema 能把一轮构建省成一次阅读验证表增行时带三列上下文设备/窗口状态/几何读数缺几何列的行无法区分「门槛不达标」与「管理态关闭」两种 false引用前篇读数时标来源篇目本篇表内四行引自开源中国卷与篇 5矩阵的跨篇累积靠来源标注才可追溯。在这里插入图片描述
