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

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

沉浸效果

一、工具类核心作用

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

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

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

二、代码结构解析

javascript 复制代码
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. 上下文获取

csharp 复制代码
const ctx = AppStorage.get<Context>(CONTEXT)
  • 前置条件:需在应用启动时注入上下文(参考EntryAbility初始化):
javascript 复制代码
// EntryAbility.ets
onWindowStageCreate(windowStage: window.WindowStage) {
  AppStorage.setOrCreate(CONTEXT, this.context)
}

2. 窗口操作

javascript 复制代码
const win = await window.getLastWindow(ctx)
await win.setWindowLayoutFullScreen(true)
  • setWindowLayoutFullScreen(true):启用沉浸式布局
  • 注意:此操作会隐藏系统默认状态栏/导航栏

3. 安全区域测量

ini 复制代码
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, ...)

  • 存储结果可供全局组件访问:
less 复制代码
@StorageLink(TOP_HEIGHT) safeTop: number = 0
@StorageLink(BOTTOM_HEIGHT) safeBottom: number = 0

四、使用示例

页面调用方式

less 复制代码
@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') 
    })
  }
}
  • 安全区域适配
less 复制代码
// 在任意组件中获取安全区域
@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. 动态适配:

  • 设备旋转后需重新测量安全区域
  • 建议监听屏幕方向变化事件:
dart 复制代码
window.on('windowSizeChange', () => this.fullScreen.enable())

4. 兼容性配置:

json 复制代码
// module.json5
"abilities": [{
  "window": {
    "layoutFullScreen": true,
    "avoidAreaType": "default"
  }
}]

5. 错误处理:

  • 建议增加重试机制
  • 可扩展错误类型判断:
go 复制代码
if (err.code === 401) {
  logger.error('Invalid parameters')
}
该封装方案通过抽象系统级API调用,实现了沉浸式效果与安全区域适配的自动化管理,使开发者能够快速构建全屏应用界面,同时保证系统UI元素与应用内容的和谐共存。
相关推荐
鱼樱前端19 分钟前
今天介绍下最新更新的Vite7
前端·vue.js
coder_pig1 小时前
跟🤡杰哥一起学Flutter (三十四、玩转Flutter手势✋)
前端·flutter·harmonyos
万少1 小时前
01-自然壁纸实战教程-免费开放啦
前端
独立开阀者_FwtCoder1 小时前
【Augment】 Augment技巧之 Rewrite Prompt(重写提示) 有神奇的魔法
前端·javascript·github
yuki_uix1 小时前
AI辅助网页设计:从图片到代码的实践探索
前端
我想说一句1 小时前
事件机制与委托:从冒泡捕获到高效编程的奇妙之旅
前端·javascript
陈随易1 小时前
MoonBit助力前端开发,加密&性能两不误,斐波那契测试提高3-4倍
前端·后端·程序员
小飞悟1 小时前
你以为 React 的事件很简单?错了,它暗藏玄机!
前端·javascript·面试
中微子2 小时前
JavaScript 事件机制:捕获、冒泡与事件委托详解
前端·javascript
Whoisshutiao2 小时前
网安-XSS-pikachu
前端·安全·网络安全