【HarmonyOS NEXT】页面沉浸式效果开发

关键词：沉浸式、安全区域、通知栏、导航栏

在移动应用开发中，应用在默认情况下窗口背景绘制范围是全屏，但UI元素被限制在安全区内（自动避开状态栏和导航栏）进行布局，来避免界面元素被状态栏和导航条遮盖（即状态栏与导航栏区域为非安全区），当应用背景色较为丰富时则会出现 app 页面的割裂感，本期将以设置窗口沉浸式和设置安全区域两点来介绍如何将应用满屏展示从而达到沉浸式的效果。当然你也可以按需利用 api 直接隐藏导航栏与通知栏。

编辑

方案一设置主窗口或子窗口的布局为沉浸式布局

设置窗口沉浸式
保存状态栏与导航栏高度
避让状态栏或导航栏

场景1 滚动容器不重叠非安全区

场景2 滚动容器重叠非安全区

方案二设置安全区域 expandSafeArea 属性达到沉浸式

场景1 滚动容器不重叠非安全区

场景2 滚动容器重叠非安全区效果

场景3 图片视频场景

方案一设置主窗口或子窗口的布局为沉浸式布局

该种方式会将整个 ability 中展示的页面都变为全屏展示效果，即从屏幕最左上角开始展示（不避开状态栏），通过获取状态栏和导航栏高度，给页面设置上下内边距，从而按需避开通知栏与导航栏实现沉浸式效果。

1. 设置窗口沉浸式

在 EntryAbility 中，在 onWindowStageCreate 阶段获取主窗口 window 对象并设置 setImmersiveModeEnabledState 为 true 即可。

2. 保存状态栏与导航栏高度

使用 getWindowAvoidArea 获取通知栏与导航栏高度并利用 AppStorage 保存，供后续页面避开该区域使用。需要注意的是：获取到的高度为 px 像素单位，须在保存或使用时进行 px2vp 单位的转换。

// 1. 获取应用主窗口。
    windowStage.getMainWindow((err, data) => {
      let errCode: number = err.code;
      if (errCode) {
        console.error('luvi > Failed to obtain the main window. Cause: ' + JSON.stringify(err));
        return;
      }

      // 2. 设置当前窗口开启沉浸式布局
      data.setImmersiveModeEnabledState(true)

      // 3. 保存窗口通知栏与导航栏高度
      let notification_avoidArea = data.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM); // 通知栏
      let navigation_avoidArea = data.getWindowAvoidArea(window.AvoidAreaType.TYPE_NAVIGATION_INDICATOR); // 导航栏

      AppStorage.setOrCreate("notificationBarHeight", px2vp(notification_avoidArea.topRect.height))
      AppStorage.setOrCreate("navigationBarHeight", px2vp(navigation_avoidArea.bottomRect.height))
    })

3. 避让状态栏或导航栏

页面使用 StorageProp 获取导航栏与通知栏高度并进行避让，并自行调节布局达到滚动时是否与通知栏或导航栏重叠效果

场景1 滚动容器不重叠非安全区

给滚动控件的父控件设置内边距即可，不让滚动范围进入到非安全区。

编辑

场景2 滚动容器重叠非安全区

给滚动控件设置内边距即可，页面滚动时即可滚动至非安全区。

编辑

方案二设置安全区域 expandSafeArea 属性达到沉浸式

我们只需增加一段代码即可实现由图 1 向图 2 转变的沉浸式效果。

参数解释：

参数名类型必填说明

types	Array <SafeAreaType>	否	非必填，配置扩展安全区域的类型。未添加metadata配置项时，页面不避让挖孔, CUTOUT类型不生效。默认值:[SafeAreaType.SYSTEM, SafeAreaType.CUTOUT, SafeAreaType.KEYBOARD]
edges	Array <SafeAreaEdge>	否	非必填，配置扩展安全区域的方向。[SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM, SafeAreaEdge.START, SafeAreaEdge.END]扩展至所有非安全区域。