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元素与应用内容的和谐共存。
相关推荐
有事没事实验室4 分钟前
node.js中的path模块
前端·css·node.js·html·html5
十盒半价15 分钟前
TypeScript + React:大型项目开发的黄金搭档
前端·typescript·trae
楚轩努力变强1 小时前
前端工程化常见问题总结
开发语言·前端·javascript·vue.js·visual studio code
鱼樱前端1 小时前
rust基础二(闭包)
前端·rust
菜鸟学Python1 小时前
Python web框架王者 Django 5.0发布:20周年了!
前端·数据库·python·django·sqlite
前端开发爱好者2 小时前
只有 7 KB!前端圈疯传的 Vue3 转场动效神库!效果炸裂!
前端·javascript·vue.js
pe7er2 小时前
RESTful API 的规范性和接口安全性如何取舍
前端·后端
Fly-ping2 小时前
【前端】JavaScript文件压缩指南
开发语言·前端·javascript
未来之窗软件服务3 小时前
免费版酒店押金原路退回系统之【房费押金计算器】实践——仙盟创梦IDE
前端·javascript·css·仙盟创梦ide·东方仙盟·酒店押金系统
拾光拾趣录3 小时前
常见 HTTP 请求头:从“为什么接口返回乱码”说起
前端·http