前言沉浸式布局是现代移动应用的标配让内容延伸到状态栏和导航栏区域实现全屏显示效果。pura/harmony-utils的WindowUtil封装了沉浸式布局的设置方法配合AppUtil.getStatusBarHeight()可以轻松实现沉浸式体验。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解帮助开发者快速掌握并应用到实际项目中。一、WindowUtil沉浸式核心APIWindowUtil提供了以下沉浸式布局方法方法说明参数使用场景setWindowLayoutFullScreen(enabled)设置全屏布局boolean沉浸式布局开启setFullScreen(enabled)设置沉浸式全屏boolean完整沉浸式体验isWindowLayoutFullScreen()判断是否全屏布局无状态查询1.1 核心特性简洁易用封装复杂API为一行调用降低使用门槛类型安全完整的TypeScript类型定义编译期即可发现错误异常处理内置异常捕获机制避免运行时崩溃配合使用与AppUtil.getStatusBarHeight()完美配合1.2 沉浸式布局方案对比方案效果适用场景全屏布局内容延伸到系统栏区域图片浏览、地图沉浸式全屏隐藏系统栏视频播放、游戏普通模式系统栏正常显示普通应用页面二、完整使用步骤2.1 安装依赖ohpminstallpura/harmony-utils2.2 开启沉浸式布局import{WindowUtil,AppUtil}frompura/harmony-utils;Button(开启沉浸式).width(100%).onClick((){try{WindowUtil.setWindowLayoutFullScreen(true);letstatusBarHeightAppUtil.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}frompura/harmony-utils;EntryComponentstruct ImmersiveDemo{Stateresult:string;StatestatusBarHeight:number0;aboutToAppear(){this.statusBarHeightAppUtil.getStatusBarHeight();}build(){Stack(){Column(){Row().height(this.statusBarHeight)Text(沉浸式内容区域).fontSize(24).fontWeight(FontWeight.Bold)}}.width(100%).height(100%)}}四、进阶用法4.1 动态沉浸式切换import{WindowUtil,AppUtil}frompura/harmony-utils;StateisImmersive:booleanfalse;toggleImmersive(){this.isImmersive!this.isImmersive;WindowUtil.setWindowLayoutFullScreen(this.isImmersive);this.statusBarHeightthis.isImmersive?AppUtil.getStatusBarHeight():0;}4.2 带状态栏颜色的沉浸式aboutToAppear(){WindowUtil.setWindowLayoutFullScreen(true);WindowUtil.setStatusBarColor(#00000000);this.statusBarHeightAppUtil.getStatusBarHeight();}五、注意事项留白处理开启沉浸式后需手动添加状态栏高度留白导航栏同理底部导航栏区域也需要类似处理颜色设置配合状态栏颜色设置实现更好的视觉效果初始化依赖使用前需确保AppUtil.init()已调用页面切换页面切换时注意沉浸式状态的一致性六、常见问题Q1: 开启沉浸式后内容被状态栏遮挡怎么办需要在顶部添加与状态栏等高的占位区域使用AppUtil.getStatusBarHeight()获取高度。Q2: setWindowLayoutFullScreen和setFullScreen有什么区别setWindowLayoutFullScreen让内容延伸到系统栏区域但系统栏仍可见setFullScreen会隐藏系统栏。Q3: 如何在部分页面开启沉浸式在目标页面的aboutToAppear中开启在aboutToDisappear中关闭即可。Q4: 沉浸式模式下软键盘弹出布局异常建议配合KeyboardUtil监听键盘高度动态调整布局避免内容被遮挡。总结WindowUtil的沉浸式布局方法让应用内容可以延伸到系统栏区域实现全屏沉浸体验。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。配合状态栏高度获取和留白处理可以打造出专业的全屏UI效果。本文基于pura/harmony-utils工具库更多功能请参考官方文档与后续系列文章。