前言

沉浸式体验是现代移动应用的标配设计。HarmonyOS提供了状态栏高度获取和沉浸式布局设置的能力，@pura/harmony-utils 的 AppUtil 将这些能力封装为简洁的方法，帮助开发者快速实现沉浸式状态栏和全屏布局。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、状态栏核心API

AppUtil 提供了以下状态栏相关方法，是沉浸式布局开发的基础：

方法	说明	返回类型	使用场景
getStatusBarHeight()	获取状态栏高度（vp）	number	沉浸式布局顶部留白
getNavigationBarHeight()	获取导航栏高度（vp）	number	底部导航栏适配

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 设备自适应：自动适配不同设备的状态栏高度

1.2 沉浸式布局适配策略

适配方式	说明	适用场景
顶部留白	添加与状态栏等高的占位区域	普通沉浸式页面
全屏模式	配合WindowUtil设置全屏	视频播放、游戏
透明状态栏	状态栏透明，内容延伸至顶部	图片浏览、地图

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 获取状态栏高度

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

Button('获取状态栏高度')
  .width('100%')
  .onClick(() => {
    try {
      let height = AppUtil.getStatusBarHeight();
      this.result = `状态栏高度: ${height}vp\n约等于 ${Math.ceil(height)} 像素`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 获取导航栏高度

Button('获取导航栏高度')
  .width('100%')
  .onClick(() => {
    try {
      let height = AppUtil.getNavigationBarHeight();
      this.result = `导航栏高度: ${height}vp`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.4 沉浸式布局适配

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

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

  build() {
    Column() {
      Row().height(this.statusBarHeight)
      Text('沉浸式布局示例')
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
    }
    .width('100%')
    .height('100%')
  }
}

三、完整页面示例

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

@Entry
@Component
struct ImmersivePage {
  @State statusBarHeight: number = 0;
  @State navBarHeight: number = 0;

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

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

四、进阶用法

4.1 配合WindowUtil实现完整沉浸式

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

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

4.2 动态监听状态栏高度变化

在横竖屏切换等场景中，状态栏高度可能发生变化，建议在 onPageShow 中重新获取：

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

五、注意事项

1. 单位为vp：返回的高度单位是vp，需要根据屏幕密度换算
2. 设备差异：不同设备的状态栏高度可能不同
3. 动态变化：状态栏高度可能因系统设置变化而改变
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 全屏模式：配合 WindowUtil 设置沉浸式窗口效果更佳

六、常见问题

Q1: 获取状态栏高度返回0怎么办？

检查 AppUtil.init() 是否已正确调用，以及是否在UIAbility的onCreate中完成初始化。

Q2: 沉浸式布局下内容被状态栏遮挡？

需要在顶部添加与状态栏等高的占位区域，或者使用padding进行偏移。

Q3: 不同设备的状态栏高度一样吗？

不同设备的状态栏高度可能不同，建议动态获取而非硬编码固定值。

Q4: 如何在HSP模块中使用？

在HSP中使用时，需要依赖主应用的 AppUtil.init() 初始化，确保主应用启动时已完成初始化。

总结

AppUtil 的状态栏高度获取方法为沉浸式布局提供了基础数据支撑。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。结合 WindowUtil 的沉浸式设置，开发者可以轻松实现全屏沉浸式体验，让应用界面更加美观。

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