HarmonyOS 鸿蒙Next中通过easyGo兼容方案配置实现平行视界

概述

平行视界是针对应用在未适配分栏布局的场景下，通过标准化配置实现宽屏、大屏设备分栏显示的系统级兼容方案。开启平行视界并分栏显示时，应用会在一个窗口中同时显示两个页面，默认情况下，两页按1:1平分窗口。左侧固定为主页，页面路由的跳转只发生在右侧，右侧显示跳转后的详情类页面。API 23版本后，支持开发者自配置。

平行视界适用于办公、邮箱、IM、电商等需要频繁切换页面的应用。例如购物类应用，在平板上运行时，左侧主页（商品分类页）保持不变，右侧展示所选分类的商品或具体商品详情，后续相关操作均在右侧进行。

本文面向中高级开发者，在开始学习之前，请完成以下前置操作：

1. 环境要求：安装最新版DevEco Studio，需支持API 23版本。
2. 知识储备：了解HarmonyOS开发基础，掌握分栏布局、路由跳转等相关知识。

本文主要内容如下：

1. 开发步骤：针对API 23及以上版本，详细介绍平行视界的完整适配流程。
2. 配置内容说明：深入讲解平行视界核心配置文件中各关键参数的含义、取值范围及配置规则，为开发者提供清晰、规范的配置指引。
3. 典型开发场景：以Navigation路由实现的购物类应用为载体，围绕平行视界高频应用场景，提供可复用的场景化解决方案。
4. 常见问题：梳理平行视界开发中的高频问题，剖析问题产生的核心原因，并给出解决方案及避坑建议，帮助开发者高效解决实战中的各项问题。

开发步骤

1. 增加配置文件

   在profile目录下创建easy_go.json兼容方案的配置文件。在module.json5配置文件中添加easyGo字段，并指向引用的easy_go.json配置文件。当前仅支持在entry模块下配置，配置后应用级生效。

   

2. 在easy_go.json配置文件中，配置平行视界的相关属性，详情可参考配置内容说明。

配置内容说明

easy_go.json 是一个标准的Object类型json文件，整体结构分为两层。第一层配置设备类型；第二层配置对应设备类型下的显示模式。

设备类型

一层配置，设置平行视界在不同设备类型下的表现。

{
  "common": {},
  "phone": {},
  "tablet": {}
}

显示模式

二层配置displayModeOptions字段，设置平行视界的显示模式，内部字段说明如下：

wideWindowMode/squareWindowMode内部字段说明：

routerSplitOptions/navigationSplitOptions内部可包含的字段说明：

navigationSplitOptions中可额外包含如下几个字段：

说明：

• routerSplitOptions和navigationSplitOptions不能同时存在。开启平行视界后，混用Router和Navigation会导致部分行为异常，因此不建议在启用平行视界的应用中混用两种路由框架。
• 当wideWindowMode/squareWindowMode配置为routerSplit时，必须同时设置routerSplitOptions字段；配置为navigationSplit时，必须同时设置navigationSplitOptions字段。

配置示例

1. Router路由下，为通用设备配置平行视界效果。

   {
     "common": {
       "displayModeOptions": {
         "wideWindowMode": "routerSplit",
         "squareWindowMode": "routerSplit",
         "routerSplitOptions": {
           "homePage": "pages/Index",
           "relatedPage": "pages/CategoryPage",
           "fullScreenPages": [
             "pages/FullScreenImagePage"
           ],
           "supportLandscapeFullscreen": true,
           "enableReducedContainerSize": true
         }
       }
     }
   }
   

2. Navigation路由下，为通用设备配置平行视界效果。

   {
     "common": {
       "displayModeOptions": {
         "wideWindowMode": "navigationSplit",
         "squareWindowMode": "navigationSplit",
         "navigationSplitOptions": {
           "homePage": "navBar",
           "relatedPage": "CategoryPage",
           "fullScreenPages": [
             "FullScreenImagePage"
           ],
           "supportLandscapeFullscreen": true,
           "enableReducedContainerSize": true
         }
       }
     }
   }
   

3. 以Navigation路由为例，为tablet设备单独配置平行视界效果。

   {
     "common": {
       "displayModeOptions": {
         "wideWindowMode": "navigationSplit",
         "squareWindowMode": "navigationSplit",
         "navigationSplitOptions": {
           "homePage": "CategoryPage",
           "fullScreenPages": [
             "FullScreenImagePage"
           ],
           "supportLandscapeFullscreen": true,
           "enableReducedContainerSize": false
         }
       }
     },
     "tablet": {
       "displayModeOptions": {
         "wideWindowMode": "original",
         "squareWindowMode": "original"
       }
     }
   }
   

典型开发场景

本章以Navigation路由实现的购物类应用为载体，介绍平行视界适配开发中的四个典型场景，并讲解如何通过easy_go配置文件进行配置。

配置主页与关联页

场景描述

默认情况下，系统会将应用的某个页面识别为主页，但是该机制在有些场景下不能准确识别主页。建议开发者主动配置主页，需要的话，还可以配置关联页。

例如在购物类应用中，开发者可以将首页设置为主页，首个商品分类页设置为启动关联页。

场景	同时配置主页和关联页	只配置主页
效果图

开发步骤

在easy_go.json配置文件中，将homePage属性设置为"navBar"，表示将Navigation首页设置为主页。将relatedPage字段设置为"CategoryPage"，表示将分类页设置为关联页。具体配置文件如下：

{
  "common": {
    "displayModeOptions": {
      "wideWindowMode": "navigationSplit",
      "navigationSplitOptions": {
        "homePage": "navBar",
        "relatedPage": "CategoryPage"
      }
    }
  }
}

路由跳转过程请求全屏

场景描述

在商品详情页，为清晰呈现商品细节，点击商品图片后，需将图片全屏展示。

实现原理

平行视界提供了全屏页能力，支持通过fullScreenPages字段指定全屏页。配置后，对应页面展示时，将暂时退出分栏模式，切换为全屏显示。页面隐藏时，恢复分栏显示。

开发步骤

在平行视界配置文件的fullScreenPages字段中，加入图片浏览页。

{
  "common": {
    "displayModeOptions": {
      ...
      "fullScreenPages": [
        "FullScreenImagePage"
      ],
    }
  }
}

路由跳转过程请求横屏显示

场景描述

在商品详情页中，“参数对比”、“配置表”类图片往往需要横屏展示，以解决竖屏模式下文字过小等问题。

实现原理

平行视界提供了配置应用请求横屏之后，退出平行视界并全屏显示的能力，支持配置supportLandscapeFullScreen字段，配置后，当应用请求全屏时，会退出分栏，全屏显示页面。

开发步骤

在easy_go.json配置文件中，将supportLandscapeFullScreen属性设置为true，配置后，当页面申请横屏时，将退出分栏模式，切换为全屏显示。

{
  "common": {
    "displayModeOptions": {
      ...
      "supportLandscapeFullScreen": true
    }
  }
}

开启虚拟容器能力

场景描述

在开启平行视界并分栏显示时，一个窗口内部会同时显示两个页面，两个页面默认按照1:1平分窗口大小。如果页面内的元素布局使用窗口宽度，可能会导致UI元素超出页面范围被截断，开发者可以开启虚拟容器能力，此时lpx单位、页面中横向断点、窗口宽度尺寸将使用原始尺寸的一半进行计算。

开发步骤

在平行视界配置文件中，将enableReducedContainerSize属性设置为true，获取平行视界后的断点。

{
  "common": {
    "displayModeOptions": {
      ...
      "enableReducedContainerSize": true
    }
  }
}

常见问题

UI元素超出页面范围，页面被截断

问题描述

开启平行视界并分栏显示时，页面内的元素超出页面范围，导致被截断，如下图所示：

原因分析

在开启平行视界并分栏显示时，一个窗口内部会同时显示两个页面，两个页面默认按照1:1平分窗口大小。如果页面内的元素布局使用窗口宽度，可能会导致UI元素超出页面范围。

解决方案

建议采取以下策略：

1. 优先使用系统组件的自适应布局能力：自适应布局。
2. 开启虚拟容器能力，在平行视界配置文件中，将enableReducedContainerSize设置为true。此时，lpx单位、页面中横向断点、窗口宽度尺寸和屏幕宽度尺寸将使用原始尺寸的一半进行计算。
3. 使用页面大小获取接口和无感监听能力： on(‘navDestinationUpdate’)：监听NavDestination组件的状态变化，API 23版本及以上，返回的当前NavDestination组件状态中会包含NavDestination组件的大小。 on(‘routerPageUpdate’)：监听Router中page页面的状态变化，API 23版本及以上，返回的当前Router页面的信息中会包含routerPage页面的大小。 onRouterPageSizeChange：当可见的Router页面大小发生变化时，会触发该回调函数。 onNavDestinationSizeChange：当可见的NavDestination大小发生变化时，会触发该回调函数。

避免左右两个页面公用一个UI资源

问题描述

左右两个分栏页面中，同一资源只在一页面中显示。

原因分析

如果左右两个分栏页面利用ArkUI的组件复用机制（例如：NodeContainer）共用了同一个UI资源，会导致对应的资源同一时刻只能在一个页面中显示。

解决方案

建议改为两边页面使用独立的资源，互不影响。

页面横竖屏适配

问题描述

平行视界场景下，使用NavDestination页面级横竖屏设置接口时，未生效。

原因分析

平行视界场景下，会同时显示左右两个页面，两个页面方向需要一致。

解决方案

推荐使用window的接口设置窗口策略。