概述

平行视界是一种针对大屏设备（折叠屏、平板）开发的系统级应用显示技术。它打破了传统移动应用只能在单一页面显示的局限，允许同一个应用在屏幕上同时开启两个页面，实现“一级页面左侧显示，二级页面右侧显示”的布局模式，适用于折叠屏展开态、平板等宽屏设备。平行视界是应用在未适配分栏布局的场景下，通过标准化配置实现宽屏、大屏设备分栏显示的系统级兼容方案。开启平行视界并分栏显示时，应用会在一个窗口中同时显示两个页面，默认情况下，两页按1:1平分窗口。从API版本23开始，支持开发者自配置。

平行视界适用于办公、邮箱、IM即时通讯、电商等需要频繁切换页面的应用。当前平行视界支持两种路由模式：导航模式和购物模式。以购物类应用在双折叠上运行为例：

• 导航模式：左侧主页（商品分类页）保持不变，右侧展示所选分类的商品或具体商品详情，后续相关操作均在右侧进行。
• 购物模式：页面路由跳转时右侧页面始终向左推入，屏幕右侧展示路由栈栈顶页面，左侧展示路由栈次栈顶页面。

页面比例

不同设备在竖屏和横屏下的默认页面比例如下：

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

为了增强灵活性，平行视界支持中间分割线拖拽交互，用户可以通过拖动中间的分割杆改变左右页面的比例（如1:1、1:2或2:1）。

典型价值场景

平行视界的核心价值在于“双页面并行”。以下是几个典型应用场景：

• 购物对比场景（电商类）：左侧浏览商品列表，左侧点击商品后，新页面在右侧打开；在右侧点击商品后，原右侧页面会左移，新页面在右侧左推打开。用户无需退回列表即可连续点击查看不同商品，实现快速比价/比货。
• 即时通讯（社交类）：左侧保持消息列表，右侧打开聊天对话框。用户可以一边回复好友，一边监控其他群聊动态。
• 内容消费（新闻/阅读类）：左侧展示文章目录或推荐列表，右侧阅读正文。在长文阅读时，左侧可作为目录随时跳转。
• 邮件/办公（效率类）：左侧查看收件箱，右侧编辑回复或查看附件，确保工作上下文不丢失。

交互规格

导航模式

导航模式能帮助用户在应用内高效地来回切换。适用于办公、邮箱、IM对话类应用。

导航模式的交互规则：

1. 在左侧页面点击任意条目时，新打开的页面覆盖右侧页面。
2. 在右侧页面点击任意条目时，新打开的页面覆盖右侧页面。
3. 触发（全局导航的）返回，右边页面回到上一层级；例如在应用首页，点击后在右侧屏幕打开新页面。再次点击右侧屏幕内容，左侧屏幕固定显示主页，右侧屏幕内容切换。

购物模式

购物模式能有效解决宽屏设备上的显示适配问题，适用于购物类的场景和应用。

购物模式的交互规则：

1. 左点右出，再次点击左侧或右侧屏幕页面，推挤进入。
2. 点击左侧屏幕，在右侧屏幕启动新的页面。点击新页面，把当前内容往左推，新的内容在右侧屏幕展示。
3. 触发（全局导航的）返回，页面右推回到上一层级。

平行视界与分栏体验对比

平行视界与分栏的目标体验不同，提供不同的接入方式，开发者根据业务诉求进行大屏适配选型。

对比项	平行视界	分栏
体验特点	为了让应用实现横屏适配，提供的系统兜底方案	为了发挥屏幕横向宽度较大的特点，满足用户高效操作的目标，需应用主动适配
约束场景	基于配置能力接入的分栏，能力相对受限，适用于希望快速接入分栏体验的应用	基于API能力接入的分栏，功能更加完整，控制更加灵活，适用于对布局体验有精细化定制诉求的应用
分栏的Pattern	无固定Pattern	左侧列表，右侧详情页
应用架构	导航模式：左侧固定显示首页，右侧显示二级或三级页面，与分栏中双分栏样式的体验基本一致；购物模式：左右侧页面可推挤显示	父子关系：具有上下级父子关系，且层级结构简单，支持侧边栏、双分栏、三分栏，支持应用自定义相关栏目布局。建议子页面的层级不超过3层
常见业务场景	无应用场景的强制约束	聊天列表+电话详情、社交关注+动态列表、邮箱列表+邮箱详情、设置分类+设置详情、商品列表+商品详情
交互操作	左右页面比例可调节	可以通过分栏的固定按钮在全屏和分栏之间快速切换；左右页面比例可调节
开发指导	请参阅平行视界开发指导	请参阅分栏开发指导

接入原则

为保证用户体验的一致性，应用在接入时应遵循以下原则：

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

开发适配过程

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

• 环境要求：安装最新版DevEco Studio，确保SDK版本不低于6.1.0(23)。
• 知识储备：了解鸿蒙开发基础，掌握分栏布局、设置组件导航和页面路由等相关知识。

本文主要内容如下：

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

开发步骤

1. 增加配置文件：在profile目录下创建兼容方案的配置文件easy_go.json（示例文件名，可自行命名）。在module.json5配置文件中添加easyGo字段，并指向引用的easy_go.json配置文件。当前仅支持在entry模块下配置，配置后应用级生效。
2. 在easy_go.json配置文件中，配置平行视界的相关属性，详情可参考配置内容说明。

配置内容说明

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

设备类型（一层配置）

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

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

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

显示模式（二层配置）

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

字段名	说明	可选
wideWindowMode	控制应用在比直板机宽的长方形宽屏窗口（>= 600vp，宽/高 > 1.2）上的显示方式。	否
squareWindowMode	控制应用在比直板机宽的方形宽屏窗口（>= 600vp，高/宽 <= 1.2，宽/高 <= 1.2）上的显示方式。	是
routerSplitOptions	平行视界使用Router分栏时的配置。	是
navigationSplitOptions	平行视界使用Navigation分栏时的配置。	是

wideWindowMode/squareWindowMode内部字段说明：

字段名	说明
navigationSplit	代表应用路由由navigation组件实现，必须配合navigationSplitOptions字段一起使用。
routerSplit	代表应用路由由router模块实现，必须配合routerSplitOptions字段一起使用。
original	关闭窗口显示模式的兼容运行行为。

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

字段名	说明	数据类型	可选
homePage	主页名称，不配置时系统采用默认的策略进行主页识别。说明：对于Navigation路由，如果将NavDestination做为主页，则配置为NavDestination的name；如果将Navigation首页作为主页，则配置为"navBar"。建议将Navigation实际主页配置为homePage。对于Router路由，配置为页面绝对路径，由配置文件中pages列表提供，例如"pages/Index"。	字符串	是
relatedPage	关联页名称，不配置时没有关联页能力。说明：内容的格式和homePage保持一致；必须有homePage才能配置relatedPage；不支持传递参数，建议配置无需动态参数的静态页面作为关联页。	字符串	是
enableReducedContainerSize	是否开启虚拟容器能力，默认值为false。false：lpx单位、页面中横向断点、窗口宽度尺寸及屏幕宽度尺寸将使用原始尺寸进行计算。true：lpx单位、页面中横向断点、窗口宽度尺寸及屏幕宽度尺寸均使用原始尺寸的缩小比例，按照右侧页面尺寸计算。说明：开启后在平行视界分栏时，整个应用内生效；平行视界退出分栏时（如：进入全屏页）自动失效；配置窗口分屏支持平行视界时，屏幕宽度尺寸将使用原始尺寸进行计算。	布尔值	是
fullScreenPages	支持全屏显示的页面数组，跳转到数组中的页面时，退出分栏显示。默认值为空数组。说明：数组中每一项内容的格式和homePage保持一致，且不能和homePage、relatedPage重复。	字符串数组	是
supportLandscapeFullscreen	应用主动请求横屏时是否全屏显示，默认值为true。true：当应用主动请求横屏时，会退出分栏全屏显示。false：当应用主动请求横屏时，仍然保持平行视界效果。	布尔值	是
dialogSupportSplit	Dialog是否支持分栏显示，默认值为true。false：弹窗居中显示。true：弹窗在右半屏显示。	布尔值	是
wideSplit	比直板机宽的长方形窗口（>= 600vp，宽/高>1.2）上的配置参数，包含字段：ratio、isDraggable。从API版本26.0.0开始支持。	对象	是
squareSplit	比直板机宽的方形窗口（>= 600vp，高/宽 <= 1.2，宽/高 <= 1.2）上的配置参数，包含字段：ratio、isDraggable。从API版本26.0.0开始支持。	对象	是
mode	路由模式，类型为非空整数，默认值为1。0：购物模式。1：导航模式。从API版本26.0.0开始支持。	数值	是
pagePairs	配置页面跳转关系对，仅在导航模式下生效。数组中的每个对象是一个{from, to}跳转关系对，用于配置从from页面跳转到to页面时触发分栏（from页面在左，to页面在右）。从API版本26.0.0开始支持。	对象数组	是
transPages	过渡页面，在购物模式下生效，配置此标签的页面将固定在右侧显示，不支持右推左。默认值为空数组。说明：NavDestination类型为NavDestinationMode.DIALOG的页面，默认属于过渡页面。数组中每一项内容的格式和homePage保持一致，且不能和homePage、relatedPage、fullScreenPages重复。从API版本26.0.0开始支持。	字符串数组	是
splitDividerColor	分割线颜色，支持配置深浅色模式，包含可选字段：light和dark。从API版本26.0.0开始支持。	对象	是
drawableRectHook	WindowProperties.drawableRect是否开启页面级容器能力，默认值为false。false：Window.drawableRect将使用原始尺寸进行计算。true：Window.drawableRect将使用原始尺寸的缩小比例，按照右侧页面尺寸计算。从API版本26.0.0开始支持。	布尔值	是
enableInSplitScreen	是否支持在窗口分屏场景进入平行视界，默认值为false。false：分屏时始终不进入平行视界。true：分屏时窗口宽高若满足条件则进入平行视界。从API版本26.0.0开始支持。	布尔值	是

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

字段名	说明	数据类型	可选
homeNavigationId	分栏Navigation的id（组件通用属性），不配置时使用最外层Navigation进行分栏。推荐开发者配置为做全局路由的Navigation的id，如果配置为其他Navigation，可能会导致布局异常。	字符串	是
disablePlaceholder	是否隐藏占位页，默认值为false。false：不隐藏占位页。true：隐藏占位页。	布尔值	是
disableDivider	是否隐藏分割线，默认值为false。false：不隐藏分割线。true：隐藏分割线。	布尔值	是

wideSplit/squareSplit内部字段说明：

字段名	说明	数据类型	可选
ratio	左右页面比例，数据格式为"正整数 | 正整数"，范围限制在1:2到2:1之间，未配置时默认为1:1，配置超出范围时默认为范围边界值。从API版本26开始支持。	字符串	是
isDraggable	是否开启分栏拖拽功能，默认值为false。false：不开启分栏拖拽功能。true：开启分栏拖拽功能。开启后ratio字段失效，默认分栏比例为1:1，使用三档吸附，在1:2、1:1和2:1之间可以进行拖动。从API版本26.0.0开始支持。	布尔值	是

pagePairs内部可以包含多对from和to字段，两个字段必须成对出现：

字段名	说明	数据类型	可选
from	触发分栏显示的源页面，格式和homePage保持一致。从API版本26.0.0开始支持。	字符串	否
to	触发分栏显示的目的页面，格式和homePage保持一致，配置为"*"表示任意页面。从API版本26.0.0开始支持。	字符串	否

splitDividerColor内部字段说明：

字段名	说明	数据类型	可选
light	浅色模式颜色，类型为十六进制字符串，格式为#AARRGGBB。从API版本26.0.0开始支持。	字符串	是
dark	深色模式颜色，类型为十六进制字符串，格式为#AARRGGBB。从API版本26.0.0开始支持。	字符串	是

说明：

• routerSplitOptions和navigationSplitOptions不能同时存在。开启平行视界后，混用Router和Navigation会导致部分行为异常，因此不建议在启用平行视界的应用中混用两种路由框架。
• 分割线颜色默认支持深浅色模式。如果应用不适配深色模式，需要配置light和dark为相同颜色。

配置示例

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

通过common为通用设备配置平行视界效果；将wideWindowMode及squareWindowMode字段设置为"routerSplit"，代表应用路由由Router模块实现；配置routerSplitOptions字段，按需设置主页、关联页、全屏页等字段。

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

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

通过common为通用设备配置平行视界效果；将wideWindowMode及squareWindowMode字段设置为"navigationSplit"，代表应用路由由Navigation组件实现；配置navigationSplitOptions字段，按需设置主页、关联页、全屏页、路由模式等字段。在平板/三折叠等长方形窗口下设置左右屏幕比例为1:2，在双折叠等方形窗口下设置左右屏幕比例为1:1。

{
  "common": {
    "displayModeOptions": {
      "wideWindowMode": "navigationSplit",
      "squareWindowMode": "navigationSplit",
      "navigationSplitOptions": {
        "homePage": "navBar",
        "relatedPage": "CategoryPage",
        "fullScreenPages": [
          "FullScreenImagePage"
        ],
        "supportLandscapeFullscreen": true,
        "enableReducedContainerSize": true,
        "wideSplit": {
          "ratio": "1 | 2"
        },
        "squareSplit": {
          "ratio": "1 | 1"
        },
        "mode": 0,
        "splitDividerColor": {
          "light": "#33FFFFFF",
          "dark": "#33000000"
        },
        "drawableRectHook": true,
        "enableInSplitScreen": true
      }
    }
  }
}

以Navigation路由为例，为tablet设备单独关闭平行视界效果

增加tablet设备配置；将wideWindowMode、squareWindowMode字段设置为"original"，关闭窗口显示模式的兼容运行行为。

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

典型开发场景

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

场景一：配置主页与关联页

场景描述：默认情况下，系统会将应用的某个页面识别为主页，但是该机制在有些场景下不能准确识别主页。建议开发者主动配置主页，需要的话，还可以配置关联页。例如在购物类应用中，开发者可以将首页设置为主页，首个商品分类页设置为启动关联页。

实现原理：平行视界提供配置主页及关联页能力。通过homePage属性设置主页，通过relatedPage属性设置关联页。

开发步骤：在easy_go.json配置文件中，将homePage属性设置为"navBar"，表示将Navigation首页设置为主页。将relatedPage属性设置为"CategoryPage"，表示将分类页设置为关联页。

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

场景二：配置路由模式

场景描述：购物类应用中，用户浏览路径通常层层深入，即从商品分类进入商品列表进行筛选比较，最终进入商品详情页完成商品挑选。相比左侧主页保持不变的导航模式，在购物模式下，页面路由跳转时右侧页面始终向左推入，屏幕右侧展示路由栈栈顶页面，左侧展示路由栈次栈顶页面，更贴合“层层深入、随时回退”的浏览体验。

实现原理：从API版本26.0.0开始，平行视界支持通过mode字段设置路由模式。

开发步骤：在easy_go.json配置文件中，将mode属性设置为0，表示将路由模式设置为购物模式。

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

场景三：设置过渡页面

场景描述：购物模式下，页面路由跳转时右侧页面始终向左推入，屏幕右侧展示路由栈栈顶页面，左侧展示路由栈次栈顶页面。但是由于某些页面（如地址编辑页）属于临时编辑操作，将此类页面固定在右侧显示，左侧分栏内容保持不变，交互体验更连贯。

实现原理：从API版本26.0.0开始，平行视界提供配置过渡页面能力。通过transPages属性设置过渡页。

开发步骤：在easy_go.json配置文件的transPages字段中，加入地址编辑页面。

{
  "common": {
    "displayModeOptions": {
      "navigationSplitOptions": {
        "homePage": "navBar",
        "relatedPage": "CategoryPage",
        "mode": 0,
        "transPages": [
          "AddressEditPage"
        ]
      }
    }
  }
}

场景四：路由跳转过程请求全屏

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

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

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

{
  "common": {
    "displayModeOptions": {
      "navigationSplitOptions": {
        "fullScreenPages": [
          "FullScreenImagePage"
        ]
      }
    }
  }
}

场景五：路由跳转过程请求横屏显示

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

实现原理：平行视界支持通过配置supportLandscapeFullscreen字段实现横屏时全屏显示页面。在easy_go.json配置文件中配置该字段值为true后，当应用请求横屏时，会退出分栏，全屏展示页面。

开发步骤：在easy_go.json配置文件中，将supportLandscapeFullscreen属性设置为true。

{
  "common": {
    "displayModeOptions": {
      "navigationSplitOptions": {
        "supportLandscapeFullscreen": true
      }
    }
  }
}

场景六：开启虚拟容器能力

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

开发步骤：在easy_go.json配置文件中，将enableReducedContainerSize属性设置为true，获取平行视界后的断点。

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

场景七：平行视界场景下触发应用内分屏

场景描述：在平板或三折叠三屏态（G态）等大屏设备上，当应用已进入平行视界分栏显示（左侧主页、右侧商品详情页）时，若用户希望在浏览商品详情的同时，打开其他页面进行比价、查询物流等操作，可以在商品详情页顶部提供分屏入口。用户点击后以主窗口形式进入系统窗口分屏，并在分屏窗口中继续保持平行视界效果，实现一边浏览商品一边使用其他应用的多任务体验。

实现原理：默认情况下，平行视界在窗口分屏场景下不会生效。平行视界提供enableInSplitScreen字段，配置为true后，当应用进入窗口分屏时，若分屏窗口宽高满足条件，则继续保持平行视界分栏显示。

开发步骤：

1. 在easy_go.json配置文件中，将enableInSplitScreen属性设置为true。

{
  "common": {
    "displayModeOptions": {
      "navigationSplitOptions": {
        "enableInSplitScreen": true
      }
    }
  }
}

2. 在商品详情页顶部添加分屏按钮。通过isEasySplit()接口判断当前是否处于平行视界分栏态，通过windowStatusType判断是否已处于窗口分屏，仅在分栏态且未分屏时显示按钮。

Row() {
  Image($r('app.media.ic_split_screen'))
    .width(24)
    .height(24)
}
// ...
.onClick(() => {
  this.startSplitScreen();
})
.visibility(this.mainWindowInfo.windowStatusType !== window.WindowStatusType.SPLIT_SCREEN &&
  this.getUIContext().isEasySplit() ? Visibility.Visible : Visibility.None)

3. 在按钮点击事件中，调用startAbility()接口拉起应用新的实例，并指定窗口分屏模式及主窗口占比，使应用以主窗口形式进入系统分屏。

private startSplitScreen(): void {
  try {
    const context = this.getUIContext().getHostContext() as common.UIAbilityContext;
    context.startAbility({
      bundleName: CommonConstants.BUNDLE_NAME,
      abilityName: 'EntryAbility',
    }, {
      windowMode: AbilityConstant.WindowMode.WINDOW_MODE_SPLIT_PRIMARY,
      splitRatio: window.SplitRatioPreference.PRIMARY_DOMINANT
    }).then(() => {
      hilog.info(0x0000, 'testTag', 'Succeeded in starting split screen mode.');
    }).catch((err: BusinessError) => {
      hilog.error(0x0000, 'testTag', `Failed to start split screen mode. Code: ${err.code}, message: ${err.message}`);
    });
  } catch (error) {
    let err = error as BusinessError;
    hilog.error(0x0000, 'testTag', `Failed to start split screen mode. Code: ${err.code}, message: ${err.message}`);
  }
}

常见问题

问题一：UI元素超出页面范围，页面元素被截断

问题描述：开启平行视界并分栏显示时，页面内的元素超出页面范围，导致被截断。

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

解决方案：

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

问题二：组件复用场景下，同一资源只在一个页面中显示

问题描述：左右两个分栏页面中，同一资源只在一页面中显示。

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

解决方案：建议改为两边页面使用独立的UI资源，互不影响，详情请参考自定义组件复用开发实践。

问题三：使用页面级窗口策略不生效

问题描述：平行视界场景下，使用NavDestination组件提供的preferredOrientation属性设置页面方向时，未生效。

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

解决方案：推荐使用窗口级方案，通过window提供的setPreferredOrientation()接口设置窗口策略。

问题四：应用设置一镜到底等转场效果不生效

问题描述：平行视界场景下，应用设置的一镜到底等转场效果不生效。

原因分析：应用接入平行视界后，系统会屏蔽或修改部分场景动效。如：

• Router类型的平行视界，系统会屏蔽所有自定义转场。
• Navigation类型的平行视界，在主页首次跳转到二级页面或者二级页面返回到首页时，系统会屏蔽所有转场，默认无动画跳转；购物模式场景下，系统会屏蔽自定义转场，默认右推左或左推右实现平移转场。

解决方案：平行视界场景下，涉及到以上转场场景时，建议关闭自定义转场，遵循系统默认效果。

问题五：运行时无法仅通过配置预知运行平行视界分栏模式

问题描述：开发者在应用运行时需要判断当前是否处于平行视界分栏模式。

原因分析：平行视界的分栏模式由平行视界的配置和设备窗口形态共同决定，应用运行过程中，窗口大小变化、分屏等操作可能导致分栏模式切换，开发者无法仅通过静态配置预知运行时的分栏模式。

解决方案：通过UIContext提供的isEasySplit()接口在运行时查询。该接口从API版本24开始支持，返回boolean类型值：true表示处于分栏模式，false表示未处于分栏模式。

总结

平行视界为开发者提供了一种高效、标准化的系统级兼容方案，使未适配分栏布局的应用能够在大屏设备上获得双页面并行的优秀体验。通过合理的配置，开发者可以灵活控制路由模式、主页与关联页、全屏页、虚拟容器等能力，满足不同业务场景的需求。在适配过程中，需注意UI元素自适应、资源复用、转场效果等常见问题，并遵循接入原则以确保用户体验的一致性。