零代码大屏适配：鸿蒙平行视界配置实战【鸿蒙心迹】

不喝水就会渴

57人浏览 · 2026-09-22 18:45:00

不喝水就会渴 · 2026-09-22 18:45:00 发布

鸿蒙平行视界：两份配置、零代码接入大屏分栏

在折叠屏与平板日益普及的今天，如何让应用优雅地利用大屏，成为鸿蒙开发者绕不开的适配课题。平行视界（EasyGo / Parallel View）作为系统级分栏方案，为尚未完成大屏适配的应用提供了低成本的兜底路径。本文将从概念、方案对比、开发配置和项目实践四个维度展开，重点说明如何仅通过两份配置、零业务代码接入大屏分栏。

1. 引言：什么是平行视界

平行视界（EasyGo / Parallel View） 是华为面向大屏设备（折叠屏展开态、平板）推出的系统级应用显示技术。它打破了传统移动应用“单窗口单页面”的局限——允许同一个应用在一个窗口中同时显示两个页面，形成“一级页面左侧显示，二级页面右侧显示”的分栏布局。

对于尚未适配大屏的应用而言，平板横屏或折叠屏展开常常带来两种不佳体验：页面被强行拉伸变形，或应用以黑边居中显示。平行视界正是系统为这类应用提供的兜底分栏方案：应用只需完成标准化配置，无需改动任何业务代码，系统便会自动按分栏规则铺开路由页面——左侧显示首页，右侧展示跳转后的二级页面。

1.1 页面比例与拖拽

设备	竖屏	横屏
折叠屏展开态	左右 1:1	左右 1:1
平板	左右 1:1	左右 1:1 / 1:2 / 2:1

平行视界支持中间分割线拖拽交互：用户可拖动分割杆在 1:1、1:2、2:1 之间切换比例（拖拽三档吸附可通过配置开启）。

1.2 两种路由模式

平行视界支持两种路由模式（mode 字段，API 26 起支持自配置）：

导航模式（mode=1，默认）：左侧主页固定不变（如商品分类页），右侧展示所选分类或商品详情，后续操作均在右侧完成。适合 IM、邮箱、办公类应用。
购物模式（mode=0）：页面路由跳转时，右侧页面始终向左推入——屏幕右侧显示路由栈栈顶页面，左侧显示次栈顶页面，更贴合“层层深入、随时回退”的浏览路径。适合购物、内容浏览类应用。

1.3 典型价值场景

官方设计指南给出了四类“双页面并行”的价值场景：

场景	平行视界带来的体验
电商购物	左侧商品列表，点击后详情在右侧打开；连续点击比价无需返回列表
即时通讯	左侧保持消息列表，右侧打开聊天对话框，一边回复一边监控群聊动态
内容消费	左侧文章目录/推荐列表，右侧阅读正文，长文阅读时可随时从左侧跳转
邮件/办公	左侧收件箱，右侧编辑回复或查看附件，工作上下文不丢失

2. 平行视界与分栏的对比

大屏适配有两条路线：平行视界（配置化接入）与分栏布局（API 接入，如 Navigation/NavDestination 自行实现双栏）。官方在设计指南中给出了明确的选型对比：

维度	平行视界	分栏
定位	为应用实现横屏适配提供的系统兜底方案	发挥横向屏幕宽度优势、满足高效操作目标，需应用主动适配
接入方式	基于配置能力接入，能力相对受限，适用于希望快速接入分栏体验的应用	基于 API 能力接入，功能更完整、控制更灵活，适用于对布局体验有精细化定制诉求的应用
固定 Pattern	无固定 Pattern	左侧列表 + 右侧详情
应用架构	导航模式：左侧固定首页、右侧二/三级页面，体验与分栏“双分栏样式”基本一致	父子层级关系，支持侧边栏、双分栏、三分栏，支持自定义栏目布局，建议子页面层级不超过 3 层
交互操作	左右页面比例可调节	支持全屏/分栏一键快速切换；左右比例可调节

2.1 选型建议

选平行视界：应用尚未做任何大屏适配，或页面层级天然符合“首页 → 二级页”结构，希望以最小成本获得完整分栏体验。它的接入成本极低（见第 3 章，仅需配置文件），但左右两栏的布局规则由系统接管，自定义空间有限。
选分栏（API 适配）：需要对分栏比例、栏目内容、断点行为做精细控制，或有侧边栏/三分栏等复杂布局诉求，愿意投入开发量重写页面结构。

两者并不互斥：官方建议的平滑路径是——先用平行视界快速获得大屏可用性，业务成熟后再演进到 API 级分栏。

2.2 接入原则（官方）

无论选择哪条路线，接入时都应遵循三条原则：

逻辑一致性：左右页面跳转符合心理预期，通常左侧为“父”层级、右侧为“子”层级；
不改变原有交互：平行视界不应破坏手机端的单窗逻辑，而是大屏态下的增强体验；
信息密度适中：分栏后单页宽度减半，需重新考量页面布局，避免内容堆叠或截断。

3. 开发步骤与典型配置

平行视界最突出的特点在于接入极简：官方开发步骤仅两步，全程零代码，只依赖配置文件。

环境要求：DevEco Studio 最新版，SDK 版本不低于 6.1.0(23)。平行视界自配置能力从 API version 23 开始支持；mode、pagePairs、transPages、wideSplit、squareSplit、splitDividerColor、enableInSplitScreen 等扩展字段从 API version 26.0.0 开始支持。

3.1 开发步骤（官方仅两步）

第一步：创建配置文件并在 module.json5 中引用

在 resources/base/profile 目录下创建 easy_go.json（文件名可自定义），并在 module.json5 中添加 easyGo 字段指向该文件。当前仅支持在 entry 模块下配置，配置后应用级生效：

// entry/src/main/module.json5
{
  "module": {
    // ...
    "easyGo": "$profile:easy_go",
    // ...
  }
}

第二步：在 easy_go.json 中配置显示模式

3.2 配置文件结构

easy_go.json 是标准 Object 类型 JSON 文件，结构分两层：第一层设备类型，第二层显示模式。

第一层设备类型：

字段名	说明	可选
`common`	通用设备配置，为所有设备提供基础默认配置	否
`phone`	phone 设备生效的配置，配置后 common 在 phone 上不再生效	是
`tablet`	tablet 设备生效的配置，配置后 common 在 tablet 上不再生效（注：自由多窗模式下暂不支持平行视界）	是

第二层 displayModeOptions：

字段名	说明	可选
`wideWindowMode`	应用在长方形宽屏窗口（>= 600vp 且宽/高 > 1.2，如平板横屏、三折叠展开态）上的显示方式	否
`squareWindowMode`	应用在方形宽屏窗口（>= 600vp 且高/宽 <= 1.2 且宽/高 <= 1.2，如双折叠展开态）上的显示方式	是
`routerSplitOptions`	使用 Router 路由时的分栏配置（与 navigationSplitOptions 互斥）	是
`navigationSplitOptions`	使用 Navigation 路由时的分栏配置	是

wideWindowMode / squareWindowMode 的取值：navigationSplit（Navigation 路由分栏）、routerSplit（Router 路由分栏）、original（关闭兼容行为）。

navigationSplitOptions 的常用字段：

字段名	说明
`homePage`	主页名称。Navigation 路由下，主页是 NavDestination 则配其 name；主页是 Navigation 首页则配 `"navBar"`。官方建议主动配置，避免系统默认识别不准
`relatedPage`	关联页名称，须依赖 homePage；建议配置无需动态参数的静态页面
`mode`	路由模式：0 = 购物模式，1 = 导航模式（默认）。API 26 起支持
`fullScreenPages`	全屏页数组，跳转到这些页面时暂时退出分栏，页面隐藏后恢复分栏
`supportLandscapeFullscreen`	应用主动请求横屏时是否全屏显示，默认 true
`enableReducedContainerSize`	虚拟容器能力：开启后 lpx 单位、横向断点、窗口/屏幕宽度尺寸按右侧页面尺寸的比例计算，解决分栏后 UI 按整窗宽度布局导致的截断问题，默认 false
`transPages`	过渡页面（购物模式下固定右侧显示、不参与右推左），如地址编辑页。API 26 起支持
`wideSplit` / `squareSplit`	长方形/方形窗口下的左右比例（`ratio`，如 `"1 \| 2"`，范围 1:2~2:1）与拖拽（`isDraggable`，三档吸附）。API 26 起支持
`splitDividerColor`	分割线颜色，支持 light/dark 深浅色。API 26 起支持
`enableInSplitScreen`	窗口分屏场景是否继续进入平行视界，默认 false。API 26 起支持
`dialogSupportSplit`	弹窗是否在右半屏显示，默认 true

注意：routerSplitOptions 与 navigationSplitOptions 不能同时存在；开启平行视界后不建议混用 Router 与 Navigation 两种路由框架，否则部分行为异常。

3.3 典型配置示例

示例一：Navigation 路由应用的完整配置（官方示例二的常见形态）

{
  "common": {
    "displayModeOptions": {
      "wideWindowMode": "navigationSplit",
      "squareWindowMode": "navigationSplit",
      "navigationSplitOptions": {
        "homePage": "navBar",
        "relatedPage": "CategoryPage",
        "supportLandscapeFullscreen": true,
        "enableReducedContainerSize": true,
        "mode": 0
      }
    }
  }
}

示例二：按设备差异化——为 tablet 单独关闭平行视界：

{
  "common": {
    "displayModeOptions": {
      "wideWindowMode": "navigationSplit",
      "squareWindowMode": "navigationSplit",
      "navigationSplitOptions": { "homePage": "navBar" }
    }
  },
  "tablet": {
    "displayModeOptions": {
      "wideWindowMode": "original",
      "squareWindowMode": "original"
    }
  }
}

运行时判断：分栏模式由配置与窗口形态共同决定。运行时如需判断是否处于分栏态，可使用 UIContext.isEasySplit()（API 24 起支持），返回 boolean。

3.4 官方避坑清单（FAQ 摘要）

UI 元素被截断：开启 enableReducedContainerSize；或使用自适应布局；或监听 on('navDestinationUpdate')（API 23+）获取分栏后的页面实际尺寸。
页面级 preferredOrientation 不生效：平行视界要求左右页面方向一致，需改用窗口级 window.setPreferredOrientation()。
一镜到底等自定义转场不生效：Navigation 类型分栏在主页与二级页互跳时系统会屏蔽转场；购物模式下默认使用右推左平移转场。建议遵循系统默认效果。
组件复用资源只在一侧显示：左右分栏若通过组件复用（如 NodeContainer）共用同一 UI 资源，同一时刻只能显示在一个页面，应改为独立资源。

4. 喵屿项目的配置实践

以喵屿（路由全部基于 Navigation）为例。该应用此前未做任何大屏适配，选择了平行视界方案，实际改动只有一次提交、两个文件、零业务代码。

4.1 实际配置

文件一：entry/src/main/module.json5

{
  "module": {
    // ...
    "easyGo": "$profile:easy_go",
    // ...
  }
}

文件二：entry/src/main/resources/base/profile/easy_go.json

{
  "common": {
    "displayModeOptions": {
      "wideWindowMode": "navigationSplit",
      "squareWindowMode": "navigationSplit",
      "navigationSplitOptions": {
        "homePage": "MainPage",
        "relatedPage": "Settings",
        "mode": 0,
        "supportLandscapeFullscreen": true,
        "enableReducedContainerSize": true,
        "fullScreenPages": [
          "PicturePreviewPage"
        ]
      }
    }
  }
}

4.2 逐项选型理由

配置项	取值	选型理由
`wideWindowMode` / `squareWindowMode`	`navigationSplit`	项目路由体系完全基于 Navigation（Index 首页 Navigation + 各页面 NavDestination），对应官方 NavigationSplit 路线
`homePage`	`"MainPage"`	对于 Navigation 路由，如果将 NavDestination 作为主页，则配置为 NavDestination 的 name；如果将 Navigation 首页作为主页，则配置为 `"navBar"`。建议将 Navigation 实际主页配置为 `homePage`
`relatedPage`	`"Settings"`	设置功能页是使用频率最高、结构稳定的静态页，作为关联页后进入应用即呈现“左侧首页导航 + 右侧设置功能内容”的完整分栏形态。按官方建议选择了无需动态参数的静态页面
`mode`	`0`（购物模式）	工具类应用的浏览路径是“首页 → 功能页 → 详情/编辑页”层层深入，购物模式的右推左（右侧=栈顶、左侧=次栈顶）比导航模式的“左侧永远固定首页”更贴合回退体验。注意 `mode` 字段自 API 26.0.0 起支持，本项目 targetSdkVersion 为 26.0.0，满足前提
`enableReducedContainerSize`	`true`	首页 Grid 卡片流与多数工具页按窗口宽度做百分比布局，分栏后单页宽度约为原来的 1/2，若不开启虚拟容器，横向断点与窗口宽度仍按整窗计算，极易出现元素截断——这正是官方 FAQ 的第一条。开启后 lpx、横向断点、窗口/屏幕宽度尺寸按右侧页面尺寸比例计算
`supportLandscapeFullscreen`	`true`	显式声明默认行为：应用主动请求横屏时（如全屏播放、沉浸类页面）退出分栏全屏显示，与系统默认一致，避免歧义
`fullScreenPages`	`"PicturePreviewPage"`	支持全屏显示的页面数组。跳转到数组中的页面时，暂时退出分栏显示；页面隐藏后恢复分栏。`PicturePreviewPage` 为大图预览页面，不适合分栏展示。说明：数组中每一项内容的格式应与 `homePage` 保持一致，且不能与 `homePage`、`relatedPage` 重复

图 1：首页分栏效果

购物模式层级推进
图 2：购物模式下“首页 → 功能页 → 详情/编辑页”层层深入

大图预览页全屏显示
图 3：大图预览页仍保留全屏模式

4.3 实践小结

成本：只需改动两个配置文件，无任何 ArkTS 代码改动，也无需发版逻辑回归路由。
生效范围：easyGo 仅支持配置在 entry 模块，配置后应用级生效——单窗（手机直板形态）行为完全不变，仅在大屏窗口形态下由系统接管分栏，符合官方“不改变原有交互”的接入原则。
验证方式：在折叠屏展开态/平板上运行，首页应居左、跳转页居右；运行时可用 this.getUIContext().isEasySplit()（API 24+）在页面内查询当前是否处于分栏态，便于做分栏态差异化的 UI 调整。

5. 总结

平行视界是鸿蒙面向折叠屏/平板等大屏设备提供的系统级分栏兜底方案：它以“一级页面居左、二级页面居右”的方式，让未做大屏适配的应用在宽屏上立刻获得合理的双栏体验。

通过官方文档与本项目实践，可以提炼出三个核心结论：

接入极其简单。官方开发步骤仅列两步——创建 easy_go.json、在 module.json5 中加一行 easyGo 引用，纯配置、零代码、应用级生效。本项目仅凭不到 20 行配置就完成了大屏适配（API 23+ 即可，SDK 6.1.0(23) 环境起步）。
选型边界清晰。平行视界是“系统兜底的配置化分栏”，适合快速接入；需要精细化布局控制时再演进到 API 级分栏。两者体验目标不同，官方给出了明确的对比与选型指引。
配置有一套完整的方法论。homePage 明确主页避免识别歧义、mode 选择与业务浏览路径匹配的路由模式（导航/购物）、enableReducedContainerSize 解决分栏后尺寸体系变化带来的截断、fullScreenPages/transPages 处理例外页面——配合官方 FAQ 的避坑清单，绝大多数应用都能以极低成本获得体验完整的大屏分栏。

对于路由已收敛到 Navigation 的应用，平行视界是目前性价比最高的大屏适配起点：一次配置提交，换全量页面在折叠屏与平板上的分栏体验。

参考文档

HarmonyOS 官方最佳实践《平行视界》：https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-easygo-parallel
HarmonyOS 官方设计指南《平行视界》：https://developer.huawei.com/consumer/cn/doc/design-guides/parallel_view-0000002588655180
官方示例代码（easygo-parallel-shopping）：https://gitcode.com/HarmonyOS_Samples/easygo-parallel-shopping