HarmonyOS 7(API 26)平行视界 EasyGo 实战：配置文件接入应用内分屏，1:2/2:1 随意切

引言：折叠屏展开的那一刻，你的应用在"整页跳"

HarmonyOS 7(API 26) 平行视界 EasyGo 实战

小伙伴拿到新折叠屏，第一件事是装自己团队的电商 Demo：展开态点商品整页跳转，十二英寸的屏幕利用率不到一半。同事一句"这应用是把平板当大号手机用"，直接点醒。

传统解法是把 Router 迁到 Navigation、页面塞进双分栏、状态同步推倒重来——伤筋动骨。HarmonyOS 7 铺了另一条路：平行视界 EasyGo 升级，不改业务代码，写一份配置文件就能让应用在大屏上以左右双页运行，路由模式、分栏比例、分割线全部可配。接下来我拆开讲：机制、配置、两种路由模式、比例与分割线、应用内分屏，最后给选型判断和一份 UI 适配清单。

一、先摆正定位：平行视界是系统级兜底，不是新框架

官方的定义很克制（平行视界能力介绍）：

平行视界是一种针对大屏设备（折叠屏、平板）开发的系统级应用显示技术。它打破了传统移动应用只能在单一页面显示的局限，允许同一个应用在屏幕上同时开启两个页面，实现"一级页面左侧显示，二级页面右侧显示"的布局模式。

• ??平行视界能力介绍：（可复制链接至网页跳转）

  https://developer.huawei.com/consumer/cn/doc/doccenter-ux-design/parallel_view-0000002588655180

从这段话里读出三个重点：

第三条要特别标注：路由模式、分栏比例拖拽、分割线颜色这些API 26的新能力，需升级至 HarmonyOS 7(API 26)并以实际支持机型为准，具体表现以真机实测为准。

还有一条硬边界：自由多窗模式下，暂不支持平行视界（官方说明，针对 tablet 设备配置项）。做窗口化场景的应用要先确认自己的主战场。

二、接入三步：一份 JSON、一行注册、应用级生效

官方把接入规定得很简单（平行视界开发指导）：profile 目录下建配置文件（示例名 easy_go.json，可自行命名），module.json5 里加 easyGo 字段指向它，仅支持 entry 模块配置，应用级生效。

• ??平行视界开发指导：（可复制链接至网页跳转）

  https://developer.huawei.com/consumer/cn/doc/doccenter-multi-device/bpta-easygo-parallel

指向写法细节以官方"开发步骤"一节为准，这里给结构示意：

{  "module": {    // easyGo 字段指向 profile 目录下的 easy_go.json（文件名可自行命名），    // 具体指向写法以官方文档《平行视界》开发指导"开发步骤"一节为准    "easyGo": "$profile:easy_go"  }}

*可左右滑动查看

easy_go.json 是标准的两层 JSON（字段名均已按官方文档核实）：

{  "common": {    "displayModeOptions": {      // 长方形宽屏窗口（>=600vp 且宽/高 > 1.2）：走 Navigation 分栏      "wideWindowMode": "navigationSplit",      // 方形宽屏窗口（>=600vp 且高/宽、宽/高均 <= 1.2）：同上      "squareWindowMode": "navigationSplit",      "navigationSplitOptions": {        "homePage": "navBar",                 // Navigation 首页做主页；用 NavDestination 做主页则配其 name        "relatedPage": "CategoryPage",        // 启动关联页：冷启动直接进列表        "mode": 0,                            // 0=购物模式（左右推挤），1=导航模式（固定覆盖），默认 1        "wideSplit":   { "ratio": "1 | 2" },  // 长方形窗口默认 1:2        "squareSplit": { "ratio": "1 | 1", "isDraggable": true }, // 方形窗口开拖拽，三档吸附        "transPages": ["AddressEditPage"],    // 过渡页固定右侧，不被推挤        "fullScreenPages": ["FullScreenImagePage"], // 进此页退出分栏，返回恢复        "splitDividerColor": {                // 分割线颜色，深浅色模式分开配          "light": "#33FFFFFF",          "dark": "#33000000"        },        "enableInSplitScreen": true,          // 窗口分屏下宽高满足条件则保持平行视界        "enableReducedContainerSize": true    // 虚拟容器：断点/宽度按右侧页面尺寸计算      }    }  },  "tablet": {    "displayModeOptions": {      "wideWindowMode": "original",           // 在 tablet 上单独关掉兼容行为      "squareWindowMode": "original"    }  }}

*可左右滑动查看

第一层是设备类型：common 提供默认配置，phone/tablet 单独覆盖。第二层里 wideWindowMode / squareWindowMode 取三个枚举值：navigationSplit（Navigation 路由）、routerSplit（Router 路由）、original（关闭兼容行为）。注意 routerSplitOptions 与 navigationSplitOptions 不能并存，官方不建议在启用平行视界的应用里混用两种路由框架。

最想强调的是 homePage：对 Navigation 路由，首页配 "navBar"；如果想让某个 NavDestination 当主页，就配它的 name。官方建议主动配置主页——默认的主页识别机制"在有些场景下不能准确识别"，识别错了，分栏的左右关系就全乱了。

三、路由模式：mode 0 和 mode 1，两种"左右"哲学

API 26 新增的 mode 字段是这期升级的核心，两种模式对应两种浏览心智（交互规则引自官方能力介绍）：

购物模式（mode: 0）：左侧列表、右侧详情，新详情从右向左推入，右侧永远显示栈顶

购物模式的 UI 样式：左侧列表页、右侧详情页，中间一条可配色的分割线。左侧点商品，新详情从右向左推入，原页面连同列表整体左移——右侧展示栈顶，左侧是次栈顶。列表列宽不变、详情约占三分之二宽，适合"层层深入、随时回退"的浏览流；临时编辑类页面（如地址编辑）用 transPages 固定在右侧，不被推挤。

导航模式（mode: 1，默认）：左侧主页固定不动，右侧内容区以覆盖方式切换

导航模式的 UI 样式：左侧"主页"固定不动、导航入口常驻，右侧内容区以覆盖方式切换，触发全局返回时右侧回到上一层级。左栏窄、右栏宽（如 1:2），视觉重心在内容区——IM 聊天、邮箱、长文阅读、分类导航这类"左固定右内容"的场景选它。

还有个精细控件 pagePairs：配置 {from, to} 跳转关系对，仅导航模式生效——from 在左、to 在右，to 可配 "*" 表示任意页面。我的理解是：mode 是全局的哲学，pagePairs 是个别入口的精修。

四、比例与分割线：1:2/2:1 预设 + 三档吸附拖拽

标题里"1:2/2:1 随意切"的出处。 navigationSplitOptions（或 routerSplitOptions）里新增了 wideSplit 和 squareSplit 两个对象，内部两个字段：

• ratio：左右页面比例，格式为 "正整数 | 正整数"，范围限制在 1:2 到 2:1 之间，未配置默认 1:1，配超了取范围边界值。我的写法习惯：平板这类长方形窗口配 "1 | 2" 让详情占主视野，双折叠的方形展开态配 "1 | 1"。

• isDraggable：开拖拽后 ratio 失效，默认从 1:1 起，三档吸附——在 1:2、1:1、2:1 之间可以拖动。用户自己找到舒服的比例，比开发者猜更聪明。

分割线也有两个开关：splitDividerColor 配深浅色两种颜色（十六进制 #AARRGGBB，官方提醒：应用不适配深色模式时，light 和 dark 配成同色）；navigationSplitOptions 独有的 disableDivider 可以干脆隐藏分割线。

配套还有一批"防止左右页打架"的字段，按官方说明列个速查表：

官方"常见问题"第一条就是 UI 元素被截断——窗口一半宽度装原来的布局，元素当然溢出。除虚拟容器，官方还给了 on('navDestinationUpdate')、onNavDestinationSizeChange() 等监听（API 23+）拿页面真实尺寸。我的顺序是：自适应布局优先，虚拟容器兜底，监听接口留给精细场景。

五、应用内分屏：分屏入口 + 一段 ArkTS

HarmonyOS 7(API 26)还有一层组合技：分栏态下点详情页的分屏入口，应用以主窗口进入系统窗口分屏，原窗口继续保持平行视界——左边列表加详情，右边再开比价或物流查询，一屏三区（官方论坛解读）。

• ??论坛官方解读：（可复制链接至网页跳转）

  https://developer.huawei.com/consumer/cn/forum/topic/0201221235973021541

接入两步：配 enableInSplitScreen: true（默认 false，不配就永远不进）；详情页加按钮，只在"分栏态 + 未分屏"时露出：

// GoodsDetailPage.ets —— 分屏入口：只在"分栏态 + 未分屏"时露出import { common, AbilityConstant } from '@kit.AbilityKit';import { window } from '@kit.ArkUI';// 按钮可见性：isEasySplit() 判断是否处于平行视界分栏态，// windowStatusType 判断是否已处于窗口分屏Button($r('app.string.enter_split'))  .visibility(this.getUIContext().isEasySplit() &&    this.mainWindowInfo.windowStatusType !== window.WindowStatusType.SPLIT_SCREEN    ? Visibility.Visible : Visibility.None)  .onClick(() => this.startSplitScreen())// 拉起应用新实例，指定主窗口占比，以主窗口形式进入系统分屏private startSplitScreen(): void {  const context = this.getUIContext().getHostContext() as common.UIAbilityContext;  context.startAbility(    { bundleName: 'com.vge.demo', abilityName: 'EntryAbility' },    {      windowMode: AbilityConstant.WindowMode.WINDOW_MODE_SPLIT_PRIMARY,      splitRatio: window.SplitRatioPreference.PRIMARY_DOMINANT    });}

*可左右滑动查看

接口名均出自官方开发指导示例代码，实际分屏效果以真机实测为准。

六、优先 Navigation，平行视界只做兜底

先给一句结论：默认路线是自己写 Navigation，平行视界排在它后面。官方的定位摆在那儿——它是针对"未适配分栏布局"场景的系统兜底方案：好处是不改业务代码就拿到两页同屏，代价是把布局控制权交给了系统。所以真正要算的是两笔账。

• 体验账：两个页面同时在屏，是真帮用户省掉了跳转和返回，还是反过来把两页都挤窄了？

• 效率账：一份 JSON 的接入成本，能不能压住后续 UI 适配的返工（截断、列数、弹窗、沉浸页）？只有当"两页同屏的收益"明显盖过"失去布局控制"的损失时，才轮到平行视界。

据此三条：

1. 能自己写，就自己写 Navigation。 有明确设计稿、要三分栏 / 跨栏联动 / 特殊转场 / 复杂状态同步、或是需要精细 UI 控制的，Navigation 分栏才是正解：布局、层级、转场都在你手里，也不需要跟 transPages、fullScreenPages 这些兜底字段斗智斗勇。

2. 轮到平行视界的，是"这一版没精力重写"的那部分。 页面关系简单、用户确实要左右对照，而你这次不想动路由和布局代码——这时候它是性价比最高的兜底。注意路由关系只是入场券，真正的判据仍是「这两个页面要不要同时被看见」：一路往里钻、看完就走的深链路，分屏反而是干扰。

3. 优先级清楚，粒度也可以自由。 主干用 Navigation 分栏：tablet 配 original 走自己的分栏，common 兜底折叠屏；同一 App 里也可以先拿平行视界把部分页面过渡过去，其余照自己的节奏改。平行视界是"先用配置接住用户"，Navigation 是"再奔理想"，两者不冲突。

七、UI 适配建议：

最后一份落地清单，按官方常见问题与字段能力整理，上线前逐条过一遍：

• 先保证单栏能跑：≥600vp 才触发分栏，断点适配是地基，平行视界只是增量。

• 详情页按"半宽"设计：List / Grid 列数按宽度降级，开 enableReducedContainerSize 让断点按右侧页面尺寸计算。

• 图片别写死宽高：用比例容器或 objectFit 裁剪，防止截断变形——官方 FAQ 第一条就是这个坑。

• 吸底按钮、悬浮球别横跨分割线：固定元素按左右两页各自对齐。

• 弹窗、半模态跟随所在页面弹出，别假设自己拿的是全屏宽度。

• 分割线颜色分 light / dark 配置；不适配深色模式就把两个配成同色，或配 disableDivider 直接隐藏。

最后一句：大屏适配的尽头不一定是重构——把路由栈交给系统，把设计稿留给自己，一份 easy_go.json 写对 homePage 和 mode，折叠屏展开的那一秒，你的应用就从"大号手机"变成了"两个页面各得其所"。

*文中代码示例仅用于演示核心逻辑，实际开发请结合业务具体需求进行调整。

来源：HarmonyOS 开发者社区

本文作者：@威哥爱编程

声明：经授权发布，观点仅代表作者本人，不代表官方立场

关注公众号，获取更多 HarmonyOS 技术内容
*广告
往期回顾 | HarmonyOS
平行视界能力升级 解锁旅行新体验
点击下方??【】，直达原文。