HarmonyOS5 鸿蒙沉浸式工具类封装~~

以下针对提供的沉浸式工具类代码进行详细解析，并结合鸿蒙开发最佳实践说明实现原理和关键步骤。

沉浸效果

一、工具类核心作用

本工具类通过封装鸿蒙窗口管理能力，实现以下核心功能：

1. 沉浸式布局：隐藏系统默认状态栏/导航栏
2. 安全区域测量：自动获取系统避让区域高度
3. 全局状态管理：通过AppStorage存储测量结果
4. 错误处理机制：提供完整的异常捕获与日志记录

适用于需要全屏显示且需适配异形屏的鸿蒙应用场景（如视频播放、游戏界面）。

二、代码结构解析

import { CONTEXT, TOP_HEIGHT, BOTTOM_HEIGHT } from '../constants'
import { window } from '@kit.ArkUI'
import { logger } from '.'

class FullScreen {
  async enable() {
    try {
      const ctx = AppStorage.get<Context>(CONTEXT)
      if (ctx) {
        const win = await window.getLastWindow(ctx)
        // 设置全屏布局
        await win.setWindowLayoutFullScreen(true)
        
        // 获取状态栏高度
        const topHeight = win.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM)
        AppStorage.setOrCreate(TOP_HEIGHT, px2vp(topHeight.topRect.height))
        
        // 获取导航条高度
        const bottomHeight = win.getWindowAvoidArea(window.AvoidAreaType.TYPE_NAVIGATION_INDICATOR)
        AppStorage.setOrCreate(BOTTOM_HEIGHT, px2vp(bottomHeight.bottomRect.height))
      }
    } catch (err) {
      logger.error('fullScreen true', err)
    }
  }
}

三、关键实现步骤

1. 上下文获取

const ctx = AppStorage.get<Context>(CONTEXT)

• 前置条件：需在应用启动时注入上下文（参考EntryAbility初始化）：

// EntryAbility.ets
onWindowStageCreate(windowStage: window.WindowStage) {
  AppStorage.setOrCreate(CONTEXT, this.context)
}

2. 窗口操作

const win = await window.getLastWindow(ctx)
await win.setWindowLayoutFullScreen(true)

• setWindowLayoutFullScreen(true)：启用沉浸式布局
• 注意：此操作会隐藏系统默认状态栏/导航栏

3. 安全区域测量

const topHeight = win.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM)
const bottomHeight = win.getWindowAvoidArea(window.AvoidAreaType.TYPE_NAVIGATION_INDICATOR)

• TYPE_SYSTEM：测量状态栏区域
• TYPE_NAVIGATION_INDICATOR：测量导航条区域
• 通过px2vp进行单位转换，适配不同分辨率设备

4. 全局状态存储

AppStorage.setOrCreate(TOP_HEIGHT, ...) AppStorage.setOrCreate(BOTTOM_HEIGHT, ...)

• 存储结果可供全局组件访问：

@StorageLink(TOP_HEIGHT) safeTop: number = 0
@StorageLink(BOTTOM_HEIGHT) safeBottom: number = 0

四、使用示例

页面调用方式

@Entry
@Component
struct VideoPlayerPage {
  private fullScreen = new FullScreen()

  aboutToAppear() {
    this.fullScreen.enable()
  }

  build() {
    Column() {
      // 视频播放器组件
    }
    .padding({ 
      top: $r('app.float.safe_area_top'),
      bottom: $r('app.float.safe_area_bottom') 
    })
  }
}

• 安全区域适配

// 在任意组件中获取安全区域
@StorageLink(TOP_HEIGHT) safeTop: number
@StorageLink(BOTTOM_HEIGHT) safeBottom: number

Column() {
  // 内容区域
}
.padding({ top: this.safeTop, bottom: this.safeBottom })

五、注意事项

1. 上下文依赖：

• 必须确保CONTEXT在AppStorage中正确初始化
• 建议在EntryAbility的onWindowStageCreate阶段注入

2. 异步处理：

• getLastWindow为异步操作，需使用async/await
• 推荐在页面生命周期（如aboutToAppear）调用

3. 动态适配：

• 设备旋转后需重新测量安全区域
• 建议监听屏幕方向变化事件：

window.on('windowSizeChange', () => this.fullScreen.enable())

4. 兼容性配置：

// module.json5
"abilities": [{
  "window": {
    "layoutFullScreen": true,
    "avoidAreaType": "default"
  }
}]

5. 错误处理：

• 建议增加重试机制
• 可扩展错误类型判断：

if (err.code === 401) {
  logger.error('Invalid parameters')
}

该封装方案通过抽象系统级API调用，实现了沉浸式效果与安全区域适配的自动化管理，使开发者能够快速构建全屏应用界面，同时保证系统UI元素与应用内容的和谐共存。