HarmonyOS 7 新特性12：平行视界深潜——easy_go 两层配置字典、版本分层与六行窗口状态验证表

1、引言

篇 5 用轻视界文集把平行视界的体验跑通跑了一遍：分栏、点选同步、分割线拖拽、单窗退化。跑完之后配置层面的问题才真正浮出来——easy_go.json 里那两层结构每层管什么？十三个选项字段哪些是 API 23 就有的、哪些是 26.0.0 才加的？两套分栏选项（router 与 navigation）为什么不能共存？以及最根本的一个问题：配置写对了，分栏就生效吗？

最后一个问题的答案是「不一定」，而「不一定」的分布是有规律的。平行视界的生效条件由配置与设备窗口状态共同决定，官方文档明说「无法仅靠静态配置预知」。所以这篇除了配置字典，还给一张验证表：六种窗口状态下 isEasySplit 的真机读数，从直板机到分栏残留态逐行实测。字典告诉你怎么配，验证表告诉你配了之后在哪些状态下会发生什么——两者合起来，下一篇同类工程就不需要再踩一遍。

环境声明：HarmonyOS 7.0.0.107 (API 26) Release，实测工程轻视界（com.qingkouwei.lightview，配置字典载体）与 EasyGoProbe（com.qingkouwei.easygoprobe，状态验证载体）；DevEco Studio 26.0.0（SDK 26.0.0.105 Release），真机 Mate 60 Pro（ALN-AL80，麒麟 9000S，直板机读数）与 MatePad Edge（QXS-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 的说明里夹了一句关键约束：自由多窗模式下暂不支持平行视界——这句的位置本身是提示：它挂在设备类型层，但实际语义在窗口状态层（验证表第六行会修正这个表述）。

第二层 displayModeOptions：wideWindowMode（长方形宽屏窗口的显示方式，≥600vp 且宽/高>1.2）/ squareWindowMode（方形宽屏窗口，≥600vp 且两向比≤1.2）/ 两套分栏选项。wideWindowMode 取值三选一：routerSplit（路由由 router 模块实现，须配 routerSplitOptions）/ navigationSplit（路由由 Navigation 组件实现，须配 navigationSplitOptions）/ original（关闭兼容运行行为）。

3.2 字段字典（十三项）

两套 options 内通用的字段，按版本分层列：

字段	作用	版本
homePage	主页（Router 为页面路径，Navigation 为 NavDestination name 或 navBar）	23
relatedPage	关联页，必须有 homePage 才能配，不支持传参	23
enableReducedContainerSize	虚拟容器：lpx/横向断点/窗口宽按右页尺寸算	23
fullScreenPages	跳转即退出分栏的页数组，不得与 home/related 重复	23
supportLandscapeFullscreen	主动横屏时是否全屏，默认 true	23
dialogSupportSplit	Dialog 是否分栏（右半屏），默认 true	23
wideSplit / squareSplit	分栏比例与拖拽（子字段 ratio、isDraggable）	26.0.0
mode	路由模式：0 购物 / 1 导航，默认 1	26.0.0
pagePairs	{from,to} 跳转关系对，仅导航模式，to 可配 *	26.0.0
transPages	过渡页，购物模式生效，固定右显不支持右推左	26.0.0
splitDividerColor	分割线颜色 light/dark，#AARRGGBB	26.0.0
drawableRectHook	drawableRect 页面级容器能力，默认 false	26.0.0
enableInSplitScreen	窗口分屏场景进入平行视界，默认 false	26.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.isDraggable=true 时 ratio 必须不出现；开启拖拽后比例由系统三档吸附接管（1:2/1:1/2:1，篇 5 与开源中国篇 10 均实测）。官方 schema 在 SDK default/hms/toolchains/modulecheck/easy_go.json，拿不准直接对照。

还有一个结构坑：二层字段必须包在 displayModeOptions 里，直接平铺 wideWindowMode 会 schema 校验失败——构建期报错信息不指字段名，第一次撞会浪费一轮排查。

4、逻辑流

配置加载与分栏判定流：

运行时判定接口 UIContext.isEasySplit()（API 24 起）是应用侧唯一的分栏感知口，配套两个尺寸回调：onRouterPageSizeChange() / onNavDestinationSizeChange()（可见页尺寸变化时回调，分栏拖拽与窗口缩放都会触发）。判定有个读时机坑：aboutToAppear 里读恒 false（分栏尚未挂载），须延迟到首帧后——篇 5 与开源中国篇 10 各踩一次，本篇立为规矩。

5、实战：六行验证表

#	设备/窗口状态	窗口几何	isEasySplit	来源
1	Mate 60 Pro 直板机全屏	388vp，宽/高 0.46，density 3.25	false	本篇新测
2	MatePad Edge 平板形态	分栏各 1418vp，1:1	true	篇 5/开源中国篇 10
3	MatePad Edge PC 形态 FULL_SCREEN	分栏各 1418vp	true	开源中国篇 15
4	MatePad Edge PC 形态 FLOATING	1100vp，宽/高 1.50	false	开源中国篇 10 诊断
5	MatePad Edge PC 形态 MAXIMIZE	1642vp，宽/高 1.60	false	开源中国篇 10 诊断
6	FLOATING（曾分栏后退回）	1418vp/栏	true（残留）	开源中国篇 15

六行读出的三条规律。其一，几何是必要非充分条件：第 4/5 行几何全达标（≥600vp 且比例>1.2）仍 false，第 1 行几何不达标直接 false——几何门槛筛掉直板机，窗口状态门槛筛掉自由多窗管理态，两道筛子串联。其二，官方「自由多窗暂不支持」的准确语义是窗口处于自由多窗管理态（第 3 行 PC 形态全屏脱离管理态即 true），设备形态只是管理态的常见载体，不是依据本身。其三，状态机不对称：第 6 行进过分栏再退回浮窗，分栏残留不释放——验证表要带历史列，单看当前窗口状态解释不了这一行。

验证表的使用规矩：环境声明报整表不报单格。单格结论（「某设备不支持平行视界」）活不过一次状态切换，矩阵只随新状态增行。本篇六行里有四行引自本卷前篇诊断读数——验证表天然是跨篇累积资产，这也是深潜篇放在体验篇之后的原因：体验篇产出读数，深潜篇把读数组织成依据。

三档吸附的补充读数（篇 5）：isDraggable=true 时分割线在 1:2/1:1/2:1 三档间吸附，拖拽过程中窗口宽读数不变——分栏比例改的是两页分配，不是窗口几何，验证表的几何列因此在拖拽下稳定。

六行状态之间的迁移关系画成图，残留态的不对称边就一目了然：

图里最值得盯的是「残留分栏」的自环：它没有出边——实测中没有任何用户操作能让残留态退回单页态（重启应用会重建窗口，那是另一条路径）。状态机的这条死边是系统行为，应用侧的应对只有让位：读到 true 就按分栏渲染，不试图纠正。

6、避坑

6.1 配置平铺与互斥字段：schema 校验失败的两种形态

现象：首版 easy_go.json 把 wideWindowMode 直接平铺在设备类型下，构建报 schema 校验失败但不指字段；第二版加了 isDraggable 又保留 ratio，再次失败。
根因：二层字段须包在 displayModeOptions 包裹层；wideSplit 的 isDraggable 与 ratio 是 schema if/then 互斥分支。
最佳实践：SDK 自带官方 schema（modulecheck/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 分栏）未实测，本篇全走 routerSplit；navigationSplitOptions 的额外字段（navBar 首页语义）放到下篇讲
• mode 0 购物模式与 pagePairs/transPages 未实测（需多页关系对场景），本篇 mode=1 导航模式
• enableReducedContainerSize 虚拟容器的 lpx 换算差异未量化实测
• 验证表第 6 行残留态的恢复条件（何时释放）未测，应用侧只让位不纠正
• 直板机横屏态（宽屏几何可达但设备类型 phone）未测，验证表这一行还空着

字典会随版本增字段，矩阵会随状态增行——这篇的价值不在今天的十三字段与六行，在「增字段查字典、增状态查矩阵」的工作方式。

具体到操作面留三条：配置改动后先过 schema 对照再过构建（6.1 的两个互斥都是构建期才报，对照 schema 能把一轮构建省成一次阅读）；验证表增行时带三列上下文（设备/窗口状态/几何读数），缺几何列的行无法区分「门槛不达标」与「管理态关闭」两种 false；引用前篇读数时标来源篇目（本篇表内四行引自开源中国卷与篇 5），矩阵的跨篇累积靠来源标注才可追溯。在这里插入图片描述