前言

沉浸式布局是现代移动应用的标配，让内容延伸到状态栏和导航栏区域，实现全屏显示效果。@pura/harmony-utils 的 WindowUtil 封装了沉浸式布局的设置方法，配合 AppUtil.getStatusBarHeight() 可以轻松实现沉浸式体验。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、WindowUtil沉浸式核心API

WindowUtil 提供了以下沉浸式布局方法：

方法	说明	参数	使用场景
setWindowLayoutFullScreen(enabled)	设置全屏布局	boolean	沉浸式布局开启
setFullScreen(enabled)	设置沉浸式全屏	boolean	完整沉浸式体验
isWindowLayoutFullScreen()	判断是否全屏布局	无	状态查询

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 配合使用：与 AppUtil.getStatusBarHeight() 完美配合

1.2 沉浸式布局方案对比

方案	效果	适用场景
全屏布局	内容延伸到系统栏区域	图片浏览、地图
沉浸式全屏	隐藏系统栏	视频播放、游戏
普通模式	系统栏正常显示	普通应用页面

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 开启沉浸式布局

import { WindowUtil, AppUtil } from '@pura/harmony-utils';

Button('开启沉浸式')
  .width('100%')
  .onClick(() => {
    try {
      WindowUtil.setWindowLayoutFullScreen(true);
      let statusBarHeight = AppUtil.getStatusBarHeight();
      this.result = `沉浸式已开启 ✅\n状态栏高度: ${statusBarHeight}vp\n请添加顶部留白避免遮挡`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 关闭沉浸式布局

Button('关闭沉浸式')
  .width('100%')
  .onClick(() => {
    try {
      WindowUtil.setWindowLayoutFullScreen(false);
      this.result = '沉浸式已关闭';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

import { WindowUtil, AppUtil } from '@pura/harmony-utils';

@Entry
@Component
struct ImmersiveDemo {
  @State result: string = '';
  @State statusBarHeight: number = 0;

  aboutToAppear() {
    this.statusBarHeight = AppUtil.getStatusBarHeight();
  }

  build() {
    Stack() {
      Column() {
        Row().height(this.statusBarHeight)
        Text('沉浸式内容区域')
          .fontSize(24)
          .fontWeight(FontWeight.Bold)
      }
    }
    .width('100%')
    .height('100%')
  }
}

四、进阶用法

4.1 动态沉浸式切换

import { WindowUtil, AppUtil } from '@pura/harmony-utils';

@State isImmersive: boolean = false;

toggleImmersive() {
  this.isImmersive = !this.isImmersive;
  WindowUtil.setWindowLayoutFullScreen(this.isImmersive);
  this.statusBarHeight = this.isImmersive ? AppUtil.getStatusBarHeight() : 0;
}

4.2 带状态栏颜色的沉浸式

aboutToAppear() {
  WindowUtil.setWindowLayoutFullScreen(true);
  WindowUtil.setStatusBarColor('#00000000');
  this.statusBarHeight = AppUtil.getStatusBarHeight();
}

五、注意事项

1. 留白处理：开启沉浸式后需手动添加状态栏高度留白
2. 导航栏同理：底部导航栏区域也需要类似处理
3. 颜色设置：配合状态栏颜色设置实现更好的视觉效果
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 页面切换：页面切换时注意沉浸式状态的一致性

六、常见问题

Q1: 开启沉浸式后内容被状态栏遮挡怎么办？

需要在顶部添加与状态栏等高的占位区域，使用 AppUtil.getStatusBarHeight() 获取高度。

Q2: setWindowLayoutFullScreen和setFullScreen有什么区别？

setWindowLayoutFullScreen 让内容延伸到系统栏区域但系统栏仍可见；setFullScreen 会隐藏系统栏。

Q3: 如何在部分页面开启沉浸式？

在目标页面的 aboutToAppear 中开启，在 aboutToDisappear 中关闭即可。

Q4: 沉浸式模式下软键盘弹出布局异常？

建议配合 KeyboardUtil 监听键盘高度，动态调整布局避免内容被遮挡。

总结

WindowUtil 的沉浸式布局方法让应用内容可以延伸到系统栏区域，实现全屏沉浸体验。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。配合状态栏高度获取和留白处理，可以打造出专业的全屏UI效果。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。