沉浸式效果避让策略失效该如何解决
================

#### 问题现象

在应用中实现沉浸式效果时：

*   当设置FullScreen属性后，Navigation导航栏不会避让状态栏，而Navigation导航栏使用padding来避让状态栏后，这一设置会影响所有navDestination页面。
*   当不设置FullScreen属性，需要铺满全屏的页面，不能在状态栏和系统底部导航条区域渲染。

问题效果如下：

<table id="zh-cn_topic_0000002548790839_table64321324141210"><tbody><tr id="ZH-CN_TOPIC_0000002655130781__zh-cn_topic_0000002548790839_row34661524141219"><td class="cellrowborder" valign="top" width="50%"><p id="ZH-CN_TOPIC_0000002655130781__zh-cn_topic_0000002548790839_p1046682420128"><span><img height="532" originheight="697" originwidth="320" src="https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/ad/v3/ZFGIRC-lQdGiYz7ecFFXaw/zh-cn_image_0000002628399652.png?HW-CC-KV=V1&amp;HW-CC-Date=20260709T134006Z&amp;HW-CC-Expire=86400&amp;HW-CC-Sign=73AD1F64D588BFC7BB97B32190548B012EDFECB69838AB25AC27F8DFFE99A88F" title="点击放大" width="266"></span></p></td><td class="cellrowborder" valign="top" width="50%"><p id="ZH-CN_TOPIC_0000002655130781__zh-cn_topic_0000002548790839_p94661424121212"><span><img height="532" originheight="697" originwidth="320" src="https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/72/v3/f5NvkhkiQsSG0st9YWzzmQ/zh-cn_image_0000002658798919.png?HW-CC-KV=V1&amp;HW-CC-Date=20260709T134006Z&amp;HW-CC-Expire=86400&amp;HW-CC-Sign=D50664085C96F059CFA7089C52A745FE7A63E7A74FDAAFD04035BF6D1ED3A979" title="点击放大" width="266"></span></p></td></tr></tbody></table>

#### 背景知识

1\. [窗口全屏布局方案](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-develop-apply-immersive-effects#section15671730447)：当不隐藏避让区时，可通过接口查询状态栏和导航条区域进行可交互元素避让处理，并设置状态栏或导航条的颜色等属性与界面元素匹配。当隐藏避让区时，通过对应接口设置全屏布局即可。

2\. [组件安全区方案](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-develop-apply-immersive-effects#section202081847174413)：布局系统保持安全区内布局，然后通过接口延伸绘制内容（如背景色，背景图）到状态栏和导航条区域实现沉浸式效果。该方案下，界面元素仅做绘制延伸，无法单独布局到状态栏和导航条区域。

3\. [padding内边距设置](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-size#padding)：通过padding设置组件的内边距以达到期望效果。

4\. [@StorageLink](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-appstorage#storagelink)：管理应用全局的UI状态。

#### 解决方案

针对不同场景下的沉浸式效果需求，可以选择设置或不设置FullScreen属性，采用不同的解决方案处理对应的问题。

1.  **设置FullScreen**：
    
    *   当应用中大多数页面需要全屏渲染时，可以在onWindowStageCreate方法中全局设置windowLayoutFullScreen为true。或者在需要的场景内单独设置windowLayoutFullScreen为true，退出时恢复原值。
        
        **代码示例如下：**
        
        EntryAbility.ets文件。
        
        import { UIAbility } from '@kit.AbilityKit';
        import { hilog } from '@kit.PerformanceAnalysisKit';
        import { window } from '@kit.ArkUI';
        
        const DOMAIN = 0x0000;
        
        export default class EntryAbility extends UIAbility {
          onDestroy(): void {
            hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onDestroy');
          }
        
          onWindowStageCreate(windowStage: window.WindowStage): void {
           _ // Main window is created,set main page for this ability_
            hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
            windowStage.loadContent('pages/XxxPage3', (err) => {
              if (err.code) {
                hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
                return;
              }
             _ // 此处添加以下代码_
              let windowClass: window.Window = windowStage.getMainWindowSync(); _// 获取应用主窗口_
              _// 设置窗口全屏_
              let isLayoutFullScreen = false;
              windowClass.setWindowLayoutFullScreen(isLayoutFullScreen).then(() => {
                console.info('Succeeded in setting the window layout to full-screen mode.');
              }).catch((err: Error) => {
                console.info('error in setting the window layout to full-screen mode.', err.message);
              });
              hilog.info(0x0000, 'testTag', 'Succeeded in loading the content.');
            });
          }
        
        
          onWindowStageDestroy(): void {
          _  // Main window is destroyed, release UI related resources_
            hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageDestroy');
          }
        
          onForeground(): void {
          _  // Ability has brought to foreground_
            hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onForeground');
          }
        
          onBackground(): void {
            _// Ability has back to background_
            hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onBackground');
          }
        };
        
        XxxPage.ets页面。
        
        import { window } from '@kit.ArkUI';
        
        @Entry
        @Component
        export struct XxxPage {
          @State isFullScreen: boolean = false;
         _ // page中使用此方式设置是否开启FullScreen_
          @StorageLink('safeTop') safeTop: number = 0;
          @StorageLink('safeBottom') safeBottom: number = 0;
          @State topFlexAreaHeight: number = 0;
          @State bottomFlexAreaHeight: number = 0;
        
          setFullScreen(value: boolean) {
            window.getLastWindow(this.getUIContext().getHostContext()).then(currentWindow => {
              currentWindow.setWindowLayoutFullScreen(value);
            });
          }
        
          build() {
            Column() {
              Flex({ direction: FlexDirection.Column }) {
                Row() {
                  Text('currentHeight：' + this.topFlexAreaHeight);
                }
                .justifyContent(FlexAlign.Center)
                .height('40%')
                .width('100%')
                .backgroundColor('#f1f3f5')
                .onAreaChange((oldValue: Area, newValue: Area) => {
                  console.info(oldValue.height.toString());
                  this.topFlexAreaHeight = newValue.height as number;
                });
        
                Flex({ direction: FlexDirection.Column, justifyContent: FlexAlign.SpaceEvenly }) {
                  Row() {
                    Text('设置全屏渲染效果')
                      .padding({ left: 15 });
                    Blank();
                    Toggle({ type: ToggleType.Switch, isOn: false })
                      .selectedColor('#0a59f7')
                      .switchPointColor('#FFFFFF')
                      .onChange((isOn: boolean) => {
                        this.isFullScreen = isOn;
                        this.setFullScreen(isOn);
                      })
                      .margin({ right: 15 });
                  }
                  .width('100%');
        
                  Row() {
                    Text('添加顶部padding')
                      .padding({ left: 15 });
                    Blank();
                    Toggle({ type: ToggleType.Switch, isOn: false })
                      .selectedColor('#0a59f7')
                      .switchPointColor('#FFFFFF')
                      .onChange((isOn: boolean) => {
                        if (isOn) {
                          this.safeTop = 40;
                        } else {
                          this.safeTop = 0;
                        }
                      })
                      .margin({ right: 15 });
                  }
                  .width('100%');
        
                  Row() {
                    Text('添加底部padding')
                      .padding({ left: 15 });
                    Blank();
                    Toggle({ type: ToggleType.Switch, isOn: false })
                      .selectedColor('#0a59f7')
                      .switchPointColor('#FFFFFF')
                      .onChange((isOn: boolean) => {
                        if (isOn) {
                          this.safeBottom = 30;
                        } else {
                          this.safeBottom = 0;
                        }
                      })
                      .margin({ right: 15 });
                  }
                  .width('100%');
                }
                .height('20%')
                .width('100%')
                .backgroundColor(Color.White);
        
                Row() {
                  Text('currentHeight：' + this.bottomFlexAreaHeight);
                }
                .justifyContent(FlexAlign.Center)
                .height('40%')
                .width('100%')
                .backgroundColor('#f1f3f5')
                .onAreaChange((oldValue: Area, newValue: Area) => {
                  console.info(oldValue.height.toString());
                  this.bottomFlexAreaHeight = newValue.height as number;
                });
        
              }
        
              .height('100%')
              .width('100%');
            }
            .padding({
              top: this.isFullScreen ? this.safeTop : 0,
              bottom: this.isFullScreen ? this.safeBottom : 0,
            })
            .height('100%')
            .width('100%');
          }
        }
        
        效果预览：
        
        ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/14/v3/yguKhBqNQaKtwp_OhcImYQ/zh-cn_image_0000002628559558.png?HW-CC-KV=V1&HW-CC-Date=20260709T134006Z&HW-CC-Expire=86400&HW-CC-Sign=6A3F85CA669E4C9AFA779743165F461F0AC01A6D3CB7BED4E1F13AEC05D7BC4B "点击放大")
        
    
    *   在FullScreen模式下，Navigation的TitleBar会被顶部状态栏遮挡，底部Tab组件会被系统导航条遮挡。可以通过设置padding来手动避让，设置padding后子页面也会受到影响，需要更新Navigation根页面中设置的padding才生效，使用AppStorage可以设置此padding值。
        
        **代码示例如下：**
        
        Index.ets页面。
        
        import { window } from '@kit.ArkUI';
        
        AppStorage.setOrCreate('safeTop', 0);
        AppStorage.setOrCreate('safeBottom', 0);
        
        @Entry
        @Component
        struct Index55 {
          @StorageLink('safeTop') safeTop: number = 0;
          @StorageLink('safeBottom') safeBottom: number = 0;
          @State isTopAvoid: boolean = false;
          @State isBottomAvoid: boolean = false;
          pageInfos: NavPathStack = new NavPathStack();
        
          aboutToAppear(): void {
        
            window.getLastWindow(this.getUIContext().getHostContext()).then(windowClass => {
              let topType = window.AvoidAreaType.TYPE\_SYSTEM;
              let statusBarArea = windowClass.getWindowAvoidArea(topType);
              this.safeTop = this.getUIContext().px2vp(statusBarArea.topRect.height);
              let navigationIndicatorArea = windowClass.getWindowAvoidArea(window.AvoidAreaType.TYPE\_NAVIGATION\_INDICATOR);
              this.safeBottom = this.getUIContext().px2vp(navigationIndicatorArea.bottomRect.height);
            });
          }
        
          setFullScreen(value: boolean) {
            window.getLastWindow(this.getUIContext().getHostContext()).then(currentWindow => {
              currentWindow.setWindowLayoutFullScreen(value);
            });
          }
        
          build() {
            Navigation(this.pageInfos) {
              Flex({ direction: FlexDirection.Column }) {
                Row() {
                  Text('点击进入子页面').onClick(() => {
                    this.pageInfos.pushPath({ name: 'XxxPage1' });
                  });
                }
                .justifyContent(FlexAlign.Center)
                .height('40%')
                .width('100%')
                .backgroundColor('#f1f3f5');
        
                Flex({ direction: FlexDirection.Column, justifyContent: FlexAlign.SpaceEvenly }) {
                  Row() {
                    Text('设置全屏渲染效果')
                      .padding({ left: 15 });
                    Blank();
                    Toggle({ type: ToggleType.Switch, isOn: false })
                      .selectedColor('#0a59f7')
                      .switchPointColor('#FFFFFF')
                      .onChange((isOn: boolean) => {
                        this.setFullScreen(isOn);
                      })
                      .margin({ right: 15 });
                  }
                  .width('100%');
        
                  Row() {
                    Text('添加顶部padding')
                      .padding({ left: 15 });
                    Blank();
                    Toggle({ type: ToggleType.Switch, isOn: false })
                      .selectedColor('#0a59f7')
                      .switchPointColor('#FFFFFF')
                      .onChange((isOn: boolean) => {
                        this.isTopAvoid = isOn;
                      })
                      .margin({ right: 15 });
                  }
                  .width('100%');
        
                  Row() {
                    Text('添加底部padding')
                      .padding({ left: 15 });
                    Blank();
                    Toggle({ type: ToggleType.Switch, isOn: false })
                      .selectedColor('#0a59f7')
                      .switchPointColor('#FFFFFF')
                      .onChange((isOn: boolean) => {
                        this.isBottomAvoid = isOn;
                      })
                      .margin({ right: 15 });
                  }
                  .width('100%');
                }
                .height('20%')
                .width('100%')
                .backgroundColor(Color.White);
        
                Row() {
        
                }
                .height('40%')
                .width('100%')
                .backgroundColor('#f1f3f5');
              }
              .height('100%')
              .width('100%');
            }
            .hideTitleBar(true)
            .height('100%')
            .width('100%')
            .padding({
              top: this.isTopAvoid ? this.safeTop : 0,
              bottom: this.isBottomAvoid ? this.safeBottom : 0,
            });
          }
        }
        
        XxxPage1.ets页面。
        
        @Builder
        export function XxxPage1Builder() {
          XxxPage1();
        }
        
        @Component
        export struct XxxPage1 {
          @StorageLink('safeTop') safeTop: number = 0;
          @StorageLink('safeBottom') safeBottom: number = 0;
          pageInfos: NavPathStack = new NavPathStack();
        
          build() {
            NavDestination() {
              Column() {
              }
              .padding({
                top: this.safeTop,
                bottom: this.safeBottom,
              });
            }.title('子页面');
          }
        }
        
        在src/main目录下的module.json5配置文件中的module字段里配置"routerMap": "$profile:router\_map"，并在src/main/resources/base/profile目录下新增router\_map.json。router\_map.json示例如下:
        
        {
          "routerMap": \[
            {
              "name": "XxxPage1",
              "pageSourceFile": "src/main/ets/pages/XxxPage1.ets",
              "buildFunction": "XxxPage1Builder",
              "data": {
                "description": "this is XxxPage1"
              }
            }
          \]
        }
        
        效果预览：
        
        ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/20/v3/BTdG20cgTb-tPES-cLq1Kg/zh-cn_image_0000002658918873.png?HW-CC-KV=V1&HW-CC-Date=20260709T134006Z&HW-CC-Expire=86400&HW-CC-Sign=EBCB744FCF409E431AD12CACF3887AAC369235D5175D27FF64E06DF7DEF1FD34 "点击放大")
        
2.  **不设置FullScreen**：
    
    当应用中大多数页面需要避让系统顶部状态栏和底部导航条时，可以不使用FullScreen模式，使用组件的扩展安全区域方式。当组件布局不需要避让时，可以通过expandSafeArea属性让组件渲染到非安全区。List组件还可以通过contentStartOffset和contentEndOffset设置内容顶部和底部的空余高度。
    
    **代码示例如下：**
    
    import { window } from '@kit.ArkUI';
    
    @Entry
    @Component
    export struct XxxPage3 {
      @StorageLink('safeTop') safeTop: SafeAreaEdge = 0;
      @StorageLink('safeBottom') safeBottom: number = 0;
      @State dataSource: number\[\] = \[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16\];
    
      aboutToAppear(): void {
        window.getLastWindow(this.getUIContext().getHostContext()).then(windowClass => {
          let topType = window.AvoidAreaType.TYPE\_SYSTEM;
          let statusBarArea = windowClass.getWindowAvoidArea(topType);
          this.safeTop = this.getUIContext().px2vp(statusBarArea.topRect.height);
          let navigationIndicatorArea = windowClass.getWindowAvoidArea(window.AvoidAreaType.TYPE\_NAVIGATION\_INDICATOR);
          this.safeBottom = this.getUIContext().px2vp(navigationIndicatorArea.bottomRect.height);
        });
      }
    
     _ // 同步获取系统信息_
      build() {
        Column() {
          List() {
            ForEach(this.dataSource, (item: number) => {
              ListItem() {
                Text(\`第${item}个item\`)
                  .align(Alignment.Center);
              }
              .height(50)
              .margin({ top: 10, bottom: 10 })
              .backgroundColor(Color.White)
              .width('100%');
            });
          }
          .backgroundColor('#f1f3f5')
       _   // 设置底部绘制延伸到头部时间栏和底部导航条_
          .expandSafeArea(\[SafeAreaType.SYSTEM\], \[SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM\])
          .contentStartOffset(this.safeTop)
          .contentEndOffset(this.safeBottom);
        }
        .width('100%')
        .height('100%');
      }
    }
    
    效果预览：
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/f4/v3/e5YwmImDRpeA2nCvXk5DyA/zh-cn_image_0000002628399654.png?HW-CC-KV=V1&HW-CC-Date=20260709T134006Z&HW-CC-Expire=86400&HW-CC-Sign=E42480BA334D12C704DBAF46DC095A27E36654F5895F7A23358A43463BF999BE "点击放大")
    
    这种方案特别需要注意的是，默认摄像头挖孔区域不为非安全区域，页面不避让挖孔。在不设置FullScreen时，竖屏状态下摄像头挖孔区域会因为导航栏非安全区域的存在避让，但在横屏状态下不会主动避让。如果要实现横屏状态下页面默认避让摄像头挖孔区域，需要在module.json5中添加配置项，具体请参考[安全区域](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-expand-safe-area)章节开头说明部分。
    

#### 总结

在应用开发中实现沉浸式效果时，需要根据具体需求选择是否设置FullScreen属性。设置FullScreen属性可以实现全屏渲染，但需要手动避让状态栏和导航条。不设置FullScreen属性则通过组件的扩展安全区域方式避让系统栏。了解并灵活运用这两种方式，可以更好地实现应用的沉浸式效果。