# 应用声明支持智慧多窗

当应用需要智慧多窗的能力时，可以通过在module.json5配置文件中对应标签添加相关字段声明支持。

#### 声明支持悬浮窗

开发者可以通过在module.json5配置文件中abilities标签下的**supportWindowMode**属性增加“**floating**”字段或使用缺省值以声明应用支持悬浮窗。

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 / disableLandscapeMultiWindow）使用。建议视频类应用配置。 | 系统识别应用为横向全屏播放： 手机 手势触发悬浮窗：横向悬浮窗 手势触发分屏：形成上下分屏 分屏样式切换：不涉及 折叠屏手机展开态 手势触发悬浮窗：横向悬浮窗 手势触发分屏：形成上下分屏 分屏样式切换：支持样式切换 系统识别应用为非横向全屏播放： 同配置为default |
| default | 缺省值，参数不配置时默认为default。 建议其他应用类配置。 | 折叠屏手机折叠态 & 手机 手势触发悬浮窗：竖向悬浮窗 手势触发分屏：形成上下分屏 分屏样式切换：不涉及 折叠屏手机展开态 手势触发悬浮窗：竖向悬浮窗 手势触发分屏：形成左右分屏 分屏样式切换：支持样式切换 |

#### 声明支持分屏

开发者可以通过在module.json5配置文件中abilities标签下的**supportWindowMode**属性增加“**split**”字段或使用缺省值以声明应用支持分屏。

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（需设置为WINDOW\_MODE\_SPLIT\_PRIMARY或者WINDOW\_MODE\_SPLIT\_SECONDARY），并可根据需要设置其他StartOptions属性或startAbility参数，如Want对象。
    
    从API版本26.0.0开始，支持使用分屏比例字段splitRatio（需设置为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 启动左侧分屏

图2 启动右侧分屏

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

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

#### 应用内多窗

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

当应用开发者需要使用应用内多窗图标时，可以使用高级组件MultiWindowEntryInAPP实现该功能。