应用声明支持智慧多窗
==========

当应用需要智慧多窗的能力时，可以通过在[module.json5配置文件](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/module-configuration-file)中对应标签添加相关字段声明支持。

#### 声明支持悬浮窗

开发者可以通过在module.json5配置文件中[abilities标签](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/module-configuration-file#abilities标签)下的**supportWindowMode**属性增加“**floating**”字段或使用缺省值以声明应用支持悬浮窗。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/3a/v3/bfKV21CfTtW4jmC9V3qXRA/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073326Z&HW-CC-Expire=86400&HW-CC-Sign=686DE71578F53EFB646A3AFE390253623F0DAA4CAE2F929F343F982A509F584A)

supportWindowMode缺省值为\["fullscreen", "split", "floating"\]。

**supportWindowMode**属性主要标识当前UIAbility所支持的窗口模式，支持的字段及含义如下表所示。

| 字段 | 说明 |
| :-- | :-- |
| fullscreen | 窗口支持全屏显示。 |
| split | 窗口支持分屏显示。 |
| floating | 窗口支持悬浮窗显示。 |

在应用声明支持智慧多窗后，还可根据业务场景的需要配置是否支持横向悬浮窗或上下分屏模式。

当应用需要支持横向悬浮窗时，开发者可以通过在module.json5配置文件中**abilities**标签下的**preferMultiWindowOrientation**属性增加“**landscape**”或者“**landscape\_auto**”配合API以声明应用支持横向悬浮窗或上下分屏模式。

**preferMultiWindowOrientation**属性主要标识当前UIAbility组件多窗布局方向，支持的字段及含义如下表所示。

| 配置值 | 说明 | 效果 |
| :-- | :-- | :-- |
| portrait | 多窗布局方向为竖向。建议竖向游戏类应用配置。 | 
**手机**

手势触发悬浮窗：竖向悬浮窗

手势触发分屏：不支持

分屏样式切换：不涉及

**折叠屏手机展开态**

手势触发悬浮窗：竖向悬浮窗

手势触发分屏：形成左右分屏

分屏样式切换：不支持样式切换

 |
| landscape | 多窗布局方向为横向，配置后支持横向悬浮窗和上下分屏。建议横向游戏类应用配置。 | 

**手机**

手势触发悬浮窗：横向悬浮窗

手势触发分屏：不支持

分屏样式切换：不涉及

**折叠屏手机展开态**

手势触发悬浮窗：横向悬浮窗

手势触发分屏：形成上下分屏

分屏样式切换：不支持样式切换

 |
| landscape\_auto | 多窗布局动态可变为横向，需要配合API（[enableLandscapeMultiWindow](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#enablelandscapemultiwindow12) / [disableLandscapeMultiWindow](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#disablelandscapemultiwindow12)）使用。建议视频类应用配置。 | 

**系统识别应用为横向全屏播放：**

**手机**

手势触发悬浮窗：横向悬浮窗

手势触发分屏：形成上下分屏

分屏样式切换：不涉及

**折叠屏手机展开态**

手势触发悬浮窗：横向悬浮窗

手势触发分屏：形成上下分屏

分屏样式切换：支持样式切换

**系统识别应用为非横向全屏播放：** 同配置为default

 |
| default | 

缺省值，参数不配置时默认为default。

建议其他应用类配置。

 | 

**折叠屏手机折叠态 & 手机**

手势触发悬浮窗：竖向悬浮窗

手势触发分屏：形成上下分屏

分屏样式切换：不涉及

**折叠屏手机展开态**

手势触发悬浮窗：竖向悬浮窗

手势触发分屏：形成左右分屏

分屏样式切换：支持样式切换

 |

#### 声明支持分屏

开发者可以通过在module.json5配置文件中[abilities标签](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/module-configuration-file#abilities标签)下的**supportWindowMode**属性增加“**split**”字段或使用缺省值以声明应用支持分屏。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/6d/v3/7Q-2tBhgQ-e9vLMNXdnwLQ/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073326Z&HW-CC-Expire=86400&HW-CC-Sign=D1ECCE6E28A93A7351C879462B4A4635F9FFC8A5FD59324A1CC6243D267EACA1)

supportWindowMode缺省值为\["fullscreen", "split", "floating"\]。

**supportWindowMode**属性主要标识当前UIAbility所支持的窗口模式，支持的字段及含义如下表所示。

| 字段 | 说明 |
| :-- | :-- |
| fullscreen | 窗口支持全屏显示。 |
| split | 窗口支持分屏显示。 |
| floating | 窗口支持悬浮窗显示。 |

#### 应用内分屏

应用内分屏功能允许[声明支持分屏](#声明支持分屏)的应用在全屏显示模式下，通过调用startAbility方法启动UIAbility并形成分屏。该功能能够增强应用的多任务处理能力，提升用户的操作体验。

此处以点击按钮启动分屏为例，主要步骤和示例如下所示：

1.  在应用中获取UIAbilityContext 对象，这是启动分屏所必需的上下文对象，用于后续调用startAbility接口。
    
    this.hostContext = this.getUIContext()?.getHostContext() as common.UIAbilityContext;
    
2.  调用startAbility接口启动UIAbility，形成分屏。调用startAbility接口时，设置StartOptions对象，需要指定窗口模式[windowMode](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-app-ability-startoptions#startoptions)（需设置为WINDOW\_MODE\_SPLIT\_PRIMARY或者WINDOW\_MODE\_SPLIT\_SECONDARY），并可根据需要设置其他StartOptions属性或startAbility参数，如Want对象。
    
    从API版本26.0.0开始，支持使用分屏比例字段[splitRatio](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-app-ability-startoptions#startoptions)（需设置为EQUAL、PRIMARY\_DOMINANT或者SECONDARY\_DOMINANT，默认为EQUAL）设置应用内分屏比例。
    
    // 创建StartOptions并设置为主窗口模式，以主窗口占较大比例，副窗口占较小比例的布局启动分屏。
    let option: StartOptions = { windowMode: AbilityConstant.WindowMode.WINDOW\_MODE\_SPLIT\_PRIMARY, splitRatio: window.SplitRatioPreference.PRIMARY\_DOMINANT };
    let want: Want = { bundleName: 'com.example.startsplitdemo', abilityName: 'EntryAbility1', moduleName: '' };
    this.hostContext?.startAbility(want, option);
    
3.  若继续执行上述步骤，可继续启动其他UIAbility窗口，呈现左右分屏或替换一侧的分屏窗口。
    

完整示例如下：

使用DevEco Studio新建Ability，创建EntryAbility1和EntryAbility2，对应文中组成分屏的两个窗口页面；同时创建EntryAbility3和EntryAbility4，对应文中不同的分屏比例，加载页面为默认页面Index.ets。

// Index.ets
import { AbilityConstant, common, StartOptions, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  @State name: string = '';
  private hostContext: common.UIAbilityContext | null = null;

  aboutToAppear(): void {
    this.hostContext = this.getUIContext()?.getHostContext() as common.UIAbilityContext;
    this.name = this.hostContext.abilityInfo.name;
  }

  build() {
    Column({ space: 20 }) {
      Text(this.name)

      Button() {
        Text('启动应用内分屏')
      }
      .height(40)
      .onClick(() => {
        // 指定拉起的分屏窗口的应用信息
        let want: Want = { bundleName: 'com.example.startsplitdemo', abilityName: 'EntryAbility1', moduleName: '' };
        // 创建StartOptions并设置窗口模式为分屏模式，左侧分屏
        let option: StartOptions = { windowMode: AbilityConstant.WindowMode.WINDOW\_MODE\_SPLIT\_PRIMARY };
        this.hostContext?.startAbility(want, option, (error: BusinessError) => {
          if (error.code) {
            return;
          }
          hilog.info(0x0000, 'testTag', '启动分屏成功');
        });
      })

      Button() {
        Text('启动另一分屏窗口')
      }
      .height(40)
      .onClick(() => {
        let want: Want = { bundleName: 'com.example.startsplitdemo', abilityName: 'EntryAbility2', moduleName: '' };
        // 指定启动EntryAbility2的窗口模式，右侧分屏
        let option: StartOptions = { windowMode: AbilityConstant.WindowMode.WINDOW\_MODE\_SPLIT\_SECONDARY };
        this.hostContext?.startAbility(want, option, (error: BusinessError) => {
          if (error.code) {
            return;
          }
          hilog.info(0x0000, 'testTag', '启动分屏成功');
        });
      })

      Button() {
        Text('以左分屏占较大比例启动')
      }
      .height(40)
      .onClick(() => {
        let want: Want = { bundleName: 'com.example.startsplitdemo', abilityName: 'EntryAbility3', moduleName: '' };
        // 指定启动EntryAbility3的窗口模式，将左分屏以较大比例，右分屏以较小比例启动应用内分屏
        let option: StartOptions = { windowMode: AbilityConstant.WindowMode.WINDOW\_MODE\_SPLIT\_SECONDARY,
          splitRatio: window.SplitRatioPreference.PRIMARY\_DOMINANT };
        this.hostContext?.startAbility(want, option, (error: BusinessError) => {
          if (error.code) {
            return;
          }
          hilog.info(0x0000, 'testTag', '启动分屏成功');
        });
      })

      Button() {
        Text('以右分屏占较大比例启动')
      }
      .height(40)
      .onClick(() => {
        let want: Want = { bundleName: 'com.example.startsplitdemo', abilityName: 'EntryAbility4', moduleName: '' };
        // 指定启动EntryAbility4的窗口模式，将左分屏以较小比例，右分屏以较大比例启动应用内分屏
        let option: StartOptions = { windowMode: AbilityConstant.WindowMode.WINDOW\_MODE\_SPLIT\_SECONDARY,
          splitRatio: window.SplitRatioPreference.SECONDARY\_DOMINANT };
        this.hostContext?.startAbility(want, option, (error: BusinessError) => {
          if (error.code) {
            return;
          }
          hilog.info(0x0000, 'testTag', '启动分屏成功');
        });
      })
    }
    .padding(20)
    .height('100%')
    .width('100%')
  }
}

图1 启动左侧分屏

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/0d/v3/oFhBJl1TSD-SdLs2paE7kA/zh-cn_image_0000002594668396.gif?HW-CC-KV=V1&HW-CC-Date=20260612T073326Z&HW-CC-Expire=86400&HW-CC-Sign=980503300CD01B22E3881A4B810191E41920D3F0738A1197E1D65D7C075BE1AE)

图2 启动右侧分屏

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/5f/v3/gV3xMQLdQhqtCpWgry9RYQ/zh-cn_image_0000002594828324.gif?HW-CC-KV=V1&HW-CC-Date=20260612T073326Z&HW-CC-Expire=86400&HW-CC-Sign=EC52D930A51F9FE61B39E7CE0E047E6FDDD8261E7AFB68595B565CFA82EB26BE)

图3 以左分屏占较大比例启动

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/fe/v3/YZGOctKPRYyqiIZLPkPdXw/zh-cn_image_0000002625187771.gif?HW-CC-KV=V1&HW-CC-Date=20260612T073326Z&HW-CC-Expire=86400&HW-CC-Sign=90B3713F71BF2DA347ECDA2FCE0C7A841023CAC658B9733FE6D1E5B9EA6E4C28)

图4 以右分屏占较大比例启动

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/e5/v3/GuKb6nx3Skepqy9busz95Q/zh-cn_image_0000002625107915.gif?HW-CC-KV=V1&HW-CC-Date=20260612T073326Z&HW-CC-Expire=86400&HW-CC-Sign=A1FEB8258D48DA0CA0813F74A79AC581FB9FDE9DAD2BF9DA9D3B9DF1C4FDD51E)

#### 应用内多窗

从HarmonyOS 6.0.0版本开始，新增支持应用内多窗。应用内多窗功能支持应用拉起分屏或全景多窗，方便用户进行多任务处理。

当应用开发者需要使用应用内多窗图标时，可以使用高级组件[MultiWindowEntryInAPP](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ui-design-multiwindowentryinapp-api)实现该功能。