顶部窗口控制条避让适配智慧多窗
===============

顶部窗口控制条是应用窗口处于智慧多窗模式下，应用顶部的操作横条 ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/20/v3/6gxdtz-zRsSi1tK9n6PE6A/zh-cn_image_0000002634008830.png?HW-CC-KV=V1&HW-CC-Date=20260709T132328Z&HW-CC-Expire=86400&HW-CC-Sign=D5D4BD92E10DE25F10AFE3123EDEB96436C21346EFDD00562363BFBB7EAD1D61) 。

顶部窗口控制条示意图如下所示：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/b6/v3/qq-vZt2MQO-5Ep8nZKCZnw/zh-cn_image_0000002664207977.png?HW-CC-KV=V1&HW-CC-Date=20260709T132328Z&HW-CC-Expire=86400&HW-CC-Sign=35743FAC5AA9C3308C2D284816402526E7BF049DC14BE6ED95AA55C18DCDBD27)

顶部横条的避让可通过以下两种方式适配：

*   使用窗口的避让能力：通过[setWindowLayoutFullScreen](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#setwindowlayoutfullscreen9)设置窗口布局是否为沉浸式布局。
    
    沉浸式布局是指应用布局不避让状态栏、导航栏以及智慧多窗顶部横条，这可能发生组件与顶部横条的重叠，导致文字遮挡、点击事件冲突等情况。非沉浸式布局是指布局避让状态栏、导航栏以及智慧多窗顶部横条，组件不会与其重叠。因此可设置isLayoutFullScreen值为false使窗口的布局为非沉浸式布局。
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/5b/v3/l3fn3hduT_Cj9lV_vylJPg/zh-cn_image_0000002664328037.png?HW-CC-KV=V1&HW-CC-Date=20260709T132328Z&HW-CC-Expire=86400&HW-CC-Sign=7EA3FA1B6F20CD90355468CCF8E168837850161A8241358182896DB5DF265F59)
    
    示例：
    
    // Index.ets
    import { BusinessError } from '@kit.BasicServicesKit';
    import { window } from '@kit.ArkUI';
    import { common } from '@kit.AbilityKit';
    
    @Entry
    @Component
    struct Index {
      @State message: string = '非沉浸式布局';
      private windowClass: window.Window | undefined = undefined;
    
      aboutToAppear(): void {
        try {
          window.getLastWindow(this.getUIContext()?.getHostContext() as common.UIAbilityContext,
            (err: BusinessError, data) => {
              const errCode: number = err.code;
              if (errCode) {
                console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(err));
                return;
              }
              this.windowClass = data;
              console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data));
            });
        } catch (exception) {
          console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(exception));
        }
      }
    
      private setWindowLayoutFullScreen(isLayoutFullScreen: boolean) {
        if (!this.windowClass) {
          return;
        }
        this.windowClass.setWindowLayoutFullScreen(isLayoutFullScreen).then(() => {
          console.info('Succeeded in setting the window layout to full-screen mode.');
        }).catch((err: BusinessError) => {
          const errCode: number = err.code;
          if (errCode) {
            console.error('Failed to set the window layout to full-screen mode. Cause:' + JSON.stringify(err));
            return;
          }
        });
      }
    
      build() {
        Stack({ alignContent: Alignment.TopStart }) {
          Column() {
            Text(this.message)
              .fontSize(25)
              .fontWeight(FontWeight.Bold)
              .margin({
                top: '2%',
                bottom: '40%'
              })
    
            Button() {
              Text('设置窗口为沉浸式布局')
                .fontSize(18)
                .fontWeight(FontWeight.Normal)
            }
            .type(ButtonType.Normal)
            .borderRadius(15)
            .margin({ top: 20 })
            .stateStyles({
              normal: {
                .backgroundColor('#ff6b89d4')
              },
              pressed: {
                .backgroundColor('#ffc81f2a')
              }
            })
            .width('60%')
            .height('6%')
            .onClick(() => {
              this.setWindowLayoutFullScreen(true);
              this.message = '沉浸式布局';
            })
    
            Button() {
              Text('设置窗口为非沉浸式布局')
                .fontSize(18)
                .fontWeight(FontWeight.Normal)
            }
            .type(ButtonType.Normal)
            .borderRadius(15)
            .margin({ top: 20 })
            .stateStyles({
              normal: {
                .backgroundColor('#ff6b89d4')
              },
              pressed: {
                .backgroundColor('#ffc81f2a')
              }
            })
            .width('60%')
            .height('6%')
            .onClick(() => {
              this.setWindowLayoutFullScreen(false);
              this.message = '非沉浸式布局';
            })
          }
          .width('100%')
        }
        .backgroundColor('#fceaeaea')
        .height('100%')
      }
    }
    
    图1 设置窗口是否为沉浸式布局
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/8e/v3/CC0ZOpmvSrSwr3WfDFxL0A/zh-cn_image_0000002633848928.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132328Z&HW-CC-Expire=86400&HW-CC-Sign=3B36B8D4B1F3F8B81CB19365180B8A12BA72A05590801CE8961940109B9E5C6B)
    
*   应用主动避让：应用不使用窗口避让能力（即设置窗口为沉浸式布局）。首次通过[getWindowAvoidArea](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#getwindowavoidarea9)接口可获取屏幕顶部需要规避的矩阵区域topRect，获取到该值后应用可对应做布局避让，并且注册[on('avoidAreaChange')](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#onavoidareachange9)监听系统避让区域变化以进行布局的动态调整。
    
    // Index.ets
    import { BusinessError } from '@kit.BasicServicesKit';
    import { common } from '@kit.AbilityKit';
    import { window } from '@kit.ArkUI';
    
    @Entry
    @Component
    struct Index {
      @State topSafeHeight: number = 0;
    
      aboutToAppear(): void {
        try {
          let windowClass: window.Window | undefined = undefined;
          window.getLastWindow(this.getUIContext()?.getHostContext() as common.UIAbilityContext,
            (err: BusinessError, data) => {
              const errCode: number = err.code;
              if (errCode) {
                console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(err));
                return;
              }
              windowClass = data;
              windowClass.setWindowLayoutFullScreen(true);
              this.topSafeHeight = this.getUIContext()?.px2vp(
                windowClass.getWindowAvoidArea(window.AvoidAreaType.TYPE\_SYSTEM).topRect.height);
              windowClass.on('avoidAreaChange', (data) => {
                if (data.type == window.AvoidAreaType.TYPE\_SYSTEM) {
                  this.topSafeHeight = this.getUIContext()?.px2vp(data.area.topRect.height)
                }
              })
              console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data));
            });
        } catch (exception) {
          console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(exception));
        }
      }
    
      build() {
        Stack({ alignContent: Alignment.TopStart }) {
          // 顶部避让区域
          Row() {
          }
          .height(this.topSafeHeight)
          .width("100%")
          .backgroundColor('#ccbbf375')
          // 根据topSafeHeight动态调整应用布局
          // ...
        }
        .height('100%')
      }
    }
    
    图2 应用主动做布局避让
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/55/v3/m6GYOTSvSoSGBOZNu7Lk1Q/zh-cn_image_0000002634008832.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132328Z&HW-CC-Expire=86400&HW-CC-Sign=A3E8DF44088E8B8A372605569A4172A6217840A43014FA0A93EAA4CF6550476B)