HarmonyOS 鸿蒙Next H5实现区域避让开发指导

HarmonyOS 鸿蒙Next H5实现区域避让开发指导

一、概述

在移动应用开发中，不同设备的屏幕形态各异，如刘海屏、全面屏、折叠屏等，同时系统状态栏、导航栏、软键盘等元素也会占据屏幕空间。为了确保应用内容在各种设备和场景下都能正常显示，不被遮挡，H5提供了一系列区域避让的机制。本文将详细介绍 H5 区域避让的实现原理、适配指导以及具体的场景案例。

使用场景

典型应用全屏窗口UI元素包括状态栏、应用界面和底部导航条，其中状态栏和导航条，通常在全屏沉浸式布局下称为避让区，避让区之外的区域称为安全区。界面元素在不同设备上存在差异，下面是不同设备上状态栏、挖孔区、导航栏的位置差异，包括：直板机、PAD、PC、折叠屏（阔折叠、双折叠、三折叠）。

说明

下图中标记区域含义：1为状态栏、2为挖孔区、3为导航栏。

图1 直板机界面元素示意图

图2 PAD界面元素示意图

图3 PC界面元素示意图

图4 折叠屏–阔折叠 界面元素示意图（左图展开态 右图折叠态）

图5 折叠屏–双折叠 界面元素示意图（左图折叠态 右图展开态）

图6 折叠屏–三折叠 界面元素示意图（左图折叠态 右图二屏折叠态 下图三屏全展开态）

图7 AvoidArea实现安全布局

图8 AvoidArea实现安全区布局+背景沉浸模式

图9 AvoidArea实现全屏布局+避让场景

图10 sample示例图

面对上述不同设备的避让区差异，可以按照如下三种场景实现应用沉浸式效果：

1.1 安全区布局场景

系统保持安全区内布局，确保应用内容不会延伸到状态栏、导航栏区域。

1.2 安全区布局+背景沉浸模式

系统保持安全区内布局，然后延伸绘制内容（如背景色、背景图）到状态栏和导航栏区域，实现沉浸式效果。

1.3 全屏布局+避让场景

系统保持全屏布局，通过相关接口获取避让区域位置、大小等信息，调整元素位置，确保不会被避让区遮挡。

二、区域避让实现原理

区域避让主要通过原生接口提供的能力实现，该接口包含几个核心方法，用于处理与区域避让相关的操作。

  • avoidAreaListener()：该方法用于添加系统规避区变化事件的监听。通过监听"avoidAreaChange"参数，当系统规避区发生变化时，如软键盘弹出或收起、设备旋转等，会触发相应的回调函数，在回调中通过 runJavaScript() 的方法将变化的数据传递给H5页面。

  • registerJavaScriptProxy()：注入JavaScript对象到window对象中，并在window对象中调用该对象的方法。实现H5页面调用原生方法。

  • getAvoidArea()：Plugins 类中的 getAvoidArea() 接口负责获取系统默认避让区域信息。此方法接收一个 AvoidAreaType 类型的参数，通过该参数可以获取当前应用窗口内容需要规避的区域。这些区域可能包括系统栏、刘海屏、手势操作区、软键盘等与窗口内容重叠时需要避让的区域。通过原生接口获取窗口实例，然后调用窗口的 getWindowAvoidArea 方法获取相应类型的避让区域，接口返回信息中包含对应避让区域是否可见、位置信息及宽高信息，并将结果返回给 H5 端。

三、适配指导

下面以VUE3框架为例，从上述的三个主要场景来进行适配指导。

3.1 安全区布局场景

安全区布局场景主要是为了确保应用内容不会被系统状态栏、导航栏等遮挡。

图7 AvoidArea实现安全布局

该场景有两种实现方法：

  • webview在安全区布局，H5页面不需要做额外处理。应用内组件默认避让状态栏、导航栏。

  • webview全屏布局，H5获取状态栏、导航栏高度，设置padding。

3.2 安全区布局+背景沉浸模式

在安全区域布局的基础上，延伸绘制内容（如背景色、背景图）到状态栏和导航条区域，实现沉浸式效果。实现方式与安全区布局相似，将webview设置全屏沉浸式，H5背景全屏、内容设置padding。

图8 AvoidArea实现安全区布局+背景沉浸模式

3.3 全屏布局+避让场景

在全屏布局中，需要隐藏系统状态栏和导航栏，并添加避让区域变化监听。根据避让区域的变化动态调整布局，确保应用在各种情况下都能正常显示。

图9 AvoidArea实现全屏布局+避让场景

3.3.1 原生侧开启全屏布局

在HarmonyOS工程的EntryAbility.ets文件中的onWindowStageCreate()生命周期内：

  1. setWindowLayoutFullScreen()接口实现界面元素延伸到状态栏和导航区域；
  2. 再通过setWindowSystemBarEnable()接口将主窗口状态栏和底部导航条隐藏，实现页面的全屏布局。

3.3.2 注入JavaScript对象

使用registerJavaScriptProxy() 接口将原生侧方法注入到H5页面中，H5页面可以调用原生方法获取状态栏和导航区域高度。

3.3.3 在H5页面中计算刘海屏/挖孔区位置

页面通过调用原生方法获取刘海屏区域位置，通过计算转换成相对位置和避让的数值。

3.3.4 H5页面示例代码

页面通过调用原生方法获取避让区域，并监听避让区域变化事件，根据回调设定不同区域的样式，实现避让。

四、场景案例

4.1 全屏布局+避让场景案例

  1. 以VUE3为例，通过调用 getAvoidArea() 接口获取初始化时的避让区域信息，并监听通过 addAvoidAreaListener() 接口注册的监听器发送的事件 ‘statusBarChange’，以便在状态变化时（如横竖屏转换）更新区域避让信息。
  2. 利用获取到的区域避让信息数据，计算所需避让的区域及其边距，并相应地更新 UI。

五、示例代码

H5区域避让的Sample示例代码地址：avoid_area_sample，开发者可以通过该地址查看完整的区域避让示例代码，并根据自己的需求进行修改和扩展。


更多关于HarmonyOS 鸿蒙Next H5实现区域避让开发指导的实战教程也可以访问 https://www.itying.com/category-93-b0.html

2 回复

HarmonyOS Next中实现H5区域避让可通过以下方式：

  1. 使用Web组件加载H5页面
  2. 通过Web组件的onTouchEvent回调监听触摸区域
  3. 利用getBoundingClientRect()获取H5元素位置信息
  4. 使用HarmonyOS的避让区域API（如setAvoidArea）设置系统避让区域
  5. 在H5侧通过CSS媒体查询适配避让区域

关键代码示例：

webView.onTouchEvent((event) => {
  const avoidArea = calculateAvoidArea(event);
  window.setAvoidArea(avoidArea);
});

注意避让区域坐标需转换为物理像素值。此方案适用于系统UI与H5内容重叠时的自动避让场景。

更多关于HarmonyOS 鸿蒙Next H5实现区域避让开发指导的实战系列教程也可以访问 https://www.itying.com/category-93-b0.html


在HarmonyOS Next中实现H5区域避让，核心是通过原生接口获取避让区域信息并动态调整布局。以下是关键点总结：

核心接口：

  • avoidAreaListener()：监听系统规避区变化（如键盘弹出/收起、屏幕旋转）
  • getAvoidArea()：获取当前需要避让的区域信息（状态栏/导航栏/刘海区等）
  • registerJavaScriptProxy()：实现H5与原生通信

三种适配方案：

  1. 安全区布局：默认避让系统UI区域
  2. 安全区+背景沉浸：内容在安全区，背景延伸到系统区域
  3. 全屏布局+动态避让：通过监听规避区变化动态调整元素位置

关键实现步骤：

  • 原生侧：设置全屏模式(setWindowLayoutFullScreen)
  • 注入JS对象到H5环境
  • H5侧：监听规避区变化事件，动态计算padding/margin
  • 处理折叠屏等特殊场景的状态变化

示例代码：

提供了完整的Vue3示例，包含规避区计算、事件监听和动态样式调整的实现。

建议参考提供的Sample代码进行具体实现，特别注意折叠屏状态变化时的布局重计算。

回到顶部