Harmony OS开发之沉浸式模式设计学习

沉浸式模式是一种旨在减少无关元素干扰使应用界面更专注于内容呈现的设计模式。在典型全屏窗口中状态栏和底部导航条被称为“避让区”其余区域为“安全区”。该模式的核心在于将应用页面延伸至避让区以实现三大目的首先是视觉统一通过使页面与避让区色调一致避免界面割裂其次是布局扩展充分利用屏幕可视区域获得更大的布局空间最后是沉浸体验在游戏或视频等特定场景下隐藏系统元素提供无干扰的全屏享受。实现方案一设置窗口的全屏模式调用窗口强制全屏布局方法setWindowLayoutFullScreen()设置窗口为沉浸式布局。页面布局范围从安全区域扩展为整个窗口包括状态栏和导航条但该方案为窗口级沉浸方案当沉浸式布局生效时应用中所有页面均开启全屏模式需要开发者在各页面进行避让处理不然可能出现元素遮挡影响用户体验。方法参数setWindowLayoutFullScreen(isLayoutFullScreen: boolean): Promise void 该方法使用Promise异步回调当沉浸式布局生效时布局不避让状态栏与底部导航区域组件可能产生与其重叠的情况而非沉浸式布局生效时布局避让状态栏与底部导航区域组件不会与其重叠。在HarmonyOS 5.0.2之前该接口在所有设备中可正常调用。参数参数名类型必填说明isLayoutFullScreenboolean是窗口的布局是否为沉浸式布局该沉浸式布局状态栏、底部导航区域仍然显示。true表示沉浸式布局false表示非沉浸式布局。返回值类型说明Promise void 无返回结果的Promise对象。官方示例// EntryAbility.etsimport{UIAbility}fromkit.AbilityKit;import{BusinessError}fromkit.BasicServicesKit;exportdefaultclassEntryAbilityextendsUIAbility{// ...onWindowStageCreate(windowStage:window.WindowStage):void{console.info(onWindowStageCreate);letwindowClass:window.Window|undefinedundefined;windowStage.getMainWindow((err:BusinessError,data){consterrCode:numbererr.code;if(errCode){console.error(Failed to obtain the main window. Cause code:${err.code}, message:${err.message});return;}windowClassdata;letisLayoutFullScreentrue;try{letpromisewindowClass.setWindowLayoutFullScreen(isLayoutFullScreen);promise.then((){console.info(Succeeded in setting the window layout to full-screen mode.);}).catch((err:BusinessError){console.error(Failed to set the window layout to full-screen mode. Cause code:${err.code}, message:${err.message});});}catch(exception){console.error(Failed to set the window layout to full-screen mode. Cause code:${exception.code}, message:${exception.message});}});}}(二扩展组件到安全区域外设置组件的expandSafeArea属性将组件的安全区域延伸至状态栏或导航条区域同时保持子组件在安全区内布局无需额外避让处理。支持指定系统避让区域类型和延伸方向实现沉浸式的方案可参考组件安全区方案。在使用expandSafeArea属性时建议组件尺寸不要设置固定宽高百分比除外。若设置固定宽高扩展方向仅支持顶部和起始侧且尺寸保持不变。当父容器为滚动容器时该属性本身不直接生效需配合子节点设置。组件必须与安全区域边界重合才能生效且仅作用于当前组件不会传递给父子组件。同时若存在position等属性会优先生效可能影响扩展效果。属性参数expandSafeArea(types?: Array, edges?: Array): T参数参数名类型必填说明typesArray否配置扩展安全区域的类型。未添加Metadata配置项时页面不避让挖孔CUTOUT类型不生效。默认值[SafeAreaType.SYSTEM, SafeAreaType.CUTOUT, SafeAreaType.KEYBOARD]非法值按默认值处理。edgesArray否配置扩展安全区域的边缘。默认值[SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM, SafeAreaEdge.START, SafeAreaEdge.END]非法值按默认值处理。扩展至所有避让区域。返回值类型说明T返回当前组件。SafeAreaType扩展安全区域的枚举类型。名称值说明SYSTEM0系统默认非安全区域包括状态栏、导航栏。CUTOUT1设备的非安全区域例如刘海屏或挖孔屏区域。KEYBOARD2软键盘区域。SafeAreaEdge扩展安全区域的边缘。名称值说明TOP0上方区域。BOTTOM1下方区域。START2前部区域。END3尾部区域。官方示例// xxx.etsEntryComponentstruct SafeAreaExample1{Statetext:stringcontroller:TextInputControllernewTextInputController()build(){Row(){Column().width(100%).height(100%)// $r(app.media.bg)需要替换为开发者所需的图像资源文件.backgroundImage($r(app.media.bg)).backgroundImageSize(ImageSize.Cover).expandSafeArea([SafeAreaType.SYSTEM],[SafeAreaEdge.TOP,SafeAreaEdge.BOTTOM])}.height(100%)}}三组件背景沉浸当组件与避让区边界重合时利用background()属性可将组件背景延伸至状态栏或导航条等避让区域从而实现视觉上的沉浸感而页面的实际布局仍保留在安全区内。这一方法属于组件级设置允许不同组件根据需求定义各异的背景色并分别扩展至对应的避让区若追求整体统一亦可在最外层父组件设置该属性以适配多样的窗口模式与方向达成全屏沉浸效果。需要注意的是这种扩展仅限于视觉绘制层面界面元素无法真正布局到系统UI区域且在页面涉及滚动时滚动内容无法延伸至系统的避让区。属性参数background(content: CustomBuilder | ResourceColor, options?: BackgroundOptions): T参数参数名类型必填说明contentCustomBuilder |ResourceColor是自定义背景。optionsBackgroundOptions否设置自定义背景选项。**说明**API version 20之前options:{align?: Alignment}返回值类型说明T返回当前组件。在使用自定义背景渲染时需注意其存在一定的延迟且无法响应事件同时不支持嵌套使用且CustomBuilder类型的背景在预览器中无法预览。从API version 20开始背景支持动态更新。当同时设置background、backgroundColor和backgroundImage时若background为ResourceColor类型或设置了ignoresLayoutSafeAreaEdges属性则background位于最底层否则位于最上层。此外若background的content参数为CustomBuilder类型background不会随CustomBuilder内容的更新而变化。ResourceColortype ResourceColor Color | number | string | Resource颜色类型用于描述资源颜色类型。类型说明Color颜色枚举值。numberHEX格式颜色支持rgb或者argb。string支持rgb、rgba或者argb的格式颜色。Resource使用引入资源的方式引入系统资源或者应用资源中的颜色。BackgroundOptions对象说明background配置选项。名称类型说明alignAlignment自定义背景与组件的对齐方式。ignoresLayoutSafeAreaEdgesArrayLayoutSafeAreaEdge配置背景要扩展到的安全区包括状态栏导航栏和safeAreaPadding。四组件设置页面沉浸通过设置ignoreLayoutSafeArea()并设置高度为LayoutPolicy.matchParent来适应父组件页面背景与布局均扩展至顶部状态栏和底部导航条。但每个页面均需单独配置并且当页面内容与避让区发生冲突时需由开发者手动进行避让处理。方法参数ignoreLayoutSafeArea(types?: Array, edges?: Array): T参数参数名类型必填说明typesArray否扩展布局安全区域的类型。默认值[LayoutSafeAreaType.SYSTEM]扩展至所有安全区域比如状态栏导航栏和组件级安全区safeAreaPadding。非法值按默认值处理。edgesArray否扩展布局安全区的边缘并且支持镜像能力。默认值[LayoutSafeAreaEdge.ALL]扩展组件所有边缘。非法值按默认值处理。返回值类型说明T返回当前组件。当组件设置ignoreLayoutSafeArea属性时若其宽高采用了LayoutPolicy.matchParent其尺寸与位置均会发生改变否则仅位置改变。结合safeAreaPadding的累积特性组件可将安全区边缘扩展至所有连续感知的安全区域。对于 List、Grid 等滚动类组件的子元素若忽略布局安全区则在滚动方向上不考虑滚动组件及其父组件的安全区域。若同时设置.ignoreLayoutSafeArea和.expandSafeArea前者优先生效后者在其基础上进行绘制扩展。LayoutSafeAreaType扩展布局安全区域的枚举类型。名称值说明SYSTEM0设置后组件的布局范围可扩展至组件级安全区safeAreaPadding和页面级安全区状态栏、导航栏、挖孔区。LayoutSafeAreaEdge扩展安全区域的边缘。名称值说明TOP0上方区域。BOTTOM1下方区域。START2前部区域。LTR模式时表示左侧区域RTL模式表示右侧区域。END3尾部区域。LTR模式时表示右侧区域RTL模式表示左侧区域。VERTICAL4垂直区域。HORIZONTAL5水平区域。ALL6全部区域。官方示例代码import{LengthMetrics}fromkit.ArkUIEntryComponentstruct IgnoreLayoutSafeAreaTest1{build(){Column(){Stack(){Row().backgroundColor(rgb(39, 135, 217)).width(75)// 固定宽度.height(75)// 固定高度.ignoreLayoutSafeArea([LayoutSafeAreaType.SYSTEM],[LayoutSafeAreaEdge.START,LayoutSafeAreaEdge.TOP])// 设置布局区域延伸取左和上方向至系统避让区SYSTEMRow().backgroundColor(rgb(0, 74, 175)).width(75).height(75)}.width(200).height(200).backgroundColor(Color.Gray).align(Alignment.TopStart)// 子组件相对于Stack容器左上对齐.padding({left:10// 设置左侧10vp普通内边距}).safeAreaPadding(LengthMetrics.vp(10))// 设置10vp安全区内边距即组件级安全区}.width(100%)}}