【鸿蒙基于API 13实战开发】—— ArkUI 页面布局(应用沉浸式效果）

最新推荐文章于 2025-12-08 20:38:51 发布

原创

最新推荐文章于 2025-12-08 20:38:51 发布 · 865 阅读

📚鸿蒙开发往期学习笔录✒️：

✒️ 鸿蒙（OpenHarmony）南向开发保姆级知识点汇总~
✒️ 鸿蒙应用开发与鸿蒙系统开发哪个更有前景？
✒️ 嵌入式开发适不适合做鸿蒙南向开发？看完这篇你就了解了~
✒️ 对于大前端开发来说，转鸿蒙开发究竟是福还是祸？
✒️ 鸿蒙岗位需求突增！移动端、PC端、IoT到底该怎么选？
✒️ 记录一场鸿蒙开发岗位面试经历~
✒️ 持续更新中……

概述

典型应用全屏窗口UI元素包括状态栏、应用界面和底部导航条，其中状态栏和导航条，通常在沉浸式布局下称为避让区；避让区之外的区域称为安全区。开发应用沉浸式效果主要指通过调整状态栏、应用界面和导航条的显示效果来减少状态栏导航条等系统界面的突兀感，从而使用户获得最佳的UI体验。

图1界面元素示意图

开发应用沉浸式效果主要要考虑如下几个设计要素：

UI元素避让处理：导航条底部区域可以响应点击事件，除此之外的可交互UI元素和应用关键信息不建议放到导航条区域。状态栏显示系统信息，如果与界面元素有冲突，需要考虑避让状态栏。
沉浸式效果处理：将状态栏和导航条颜色与界面元素颜色相匹配，不出现明显的突兀感。

针对上面的设计要求，可以通过如下两种方式实现应用沉浸式效果：

窗口全屏布局方案：调整布局系统为全屏布局，界面元素延伸到状态栏和导航条区域实现沉浸式效果。当不隐藏避让区时，可通过接口查询状态栏和导航条区域进行可交互元素避让处理，并设置状态栏或导航条的颜色等属性与界面元素匹配。当隐藏避让区时，通过对应接口设置全屏布局即可。
组件安全区方案：布局系统保持安全区内布局，然后通过接口延伸绘制内容（如背景色，背景图）到状态栏和导航条区域实现沉浸式效果。

该方案下，界面元素仅做绘制延伸，无法单独布局到状态栏和导航条区域，针对需要单独布局UI元素到状态栏和导航条区域的场景建议使用窗口全屏布局方案处理。

窗口全屏布局方案

窗口全屏布局方案主要涉及以下应用扩展布局，全屏显示，不隐藏避让区和应用扩展布局，隐藏避让区两个应用场景。

应用扩展布局，全屏显示，不隐藏避让区

可以通过调用窗口强制全屏布局接口 setWindowLayoutFullScreen() 实现界面元素延伸到状态栏和导航条；然后通过接口 getWindowAvoidArea() 和 on(‘avoidAreaChange’) 获取并动态监听避让区域的变更信息，页面布局根据避让区域信息进行动态调整；设置状态栏或导航条的颜色等属性与界面元素进行匹配。

调用setWindowLayoutFullScreen()接口设置窗口全屏。

// EntryAbility.ets
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...

  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', (err, data) => {
      if (err.code) {
        return;
      }

      let windowClass: window.Window = windowStage.getMainWindowSync(); // 获取应用主窗口
      // 1. 设置窗口全屏
      let isLayoutFullScreen = true;
      windowClass.setWindowLayoutFullScreen(isLayoutFullScreen).then(() => {
        console.info('Succeeded in setting the window layout to full-screen mode.');
      }).catch((err: BusinessError) => {
        console.error('Failed to set the window layout to full-screen mode. Cause:' + JSON.stringify(err));
      });
      // 进行后续步骤2-3中的操作
    });
  }
}

使用 getWindowAvoidArea() 接口获取当前布局遮挡区域（例如状态栏、导航条）。

// EntryAbility.ets
// 2. 获取布局避让遮挡的区域
let type = window.AvoidAreaType.TYPE_NAVIGATION_INDICATOR; // 以导航条避让为例
let avoidArea = windowClass.getWindowAvoidArea(type);
let bottomRectHeight = avoidArea.bottomRect.height; // 获取到导航条区域的高度
AppStorage.setOrCreate('bottomRectHeight', bottomRectHeight);

type = window.AvoidAreaType.TYPE_SYSTEM; // 以状态栏避让为例
avoidArea = windowClass.getWindowAvoidArea(type);
let topRectHeight = avoidArea.topRect.height; // 获取状态栏区域高度     
AppStorage.setOrCreate('topRectHeight', topRectHeight);