bd5935e5创建于 2025年3月18日历史提交

@ohos.app.ability.StartOptions (StartOptions)

StartOptions可以作为startAbility()的入参，用于指定目标Ability的窗口模式。

说明：

本模块首批接口从API version 9 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

本模块接口仅可在Stage模型下使用。

导入模块

import { StartOptions } from '@kit.AbilityKit';

属性

系统能力：SystemCapability.Ability.AbilityRuntime.Core

名称	类型	只读	可选	说明
windowMode¹²⁺	number	否	是	启动Ability时的窗口模式，详见WindowMode。
displayId	number	否	是	屏幕ID模式。默认是0，表示当前屏幕。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
withAnimation¹¹⁺	boolean	否	是	启动Ability时是否具有动画效果。true表示具有动画效果，false表示不具有动画效果。约束： 1.该功能仅在2in1和tablet设备上生效。 2.调用方与目标方必须为同一应用。
windowLeft¹¹⁺	number	否	是	窗口左边的位置，单位为px。
windowTop¹¹⁺	number	否	是	窗口顶部的位置，单位为px。
windowWidth¹¹⁺	number	否	是	窗口的宽度，单位为px。
windowHeight¹¹⁺	number	否	是	窗口的高度，单位为px。
processMode¹²⁺	contextConstant.ProcessMode	否	是	进程模式。约束： 1.该功能仅在2in1和tablet设备上生效。 2.仅在UIAbilityContext.startAbility中生效。 3.processMode和startupVisibility必须同时设置。
startupVisibility¹²⁺	contextConstant.StartupVisibility	是	否	Ability启动后的可见性。约束： 1.该功能仅在2in1和tablet设备上生效。 2.仅在UIAbilityContext.startAbility中生效。 3.processMode和startupVisibility必须同时设置。
startWindowIcon¹⁴⁺	image.PixelMap	否	是	在应用内启动UIAbility时，启动页所显示的图标。如果未配置该字段，则默认采用module.json5文件中startWindowIcon字段的配置。约束： 1.该功能仅在2in1和tablet设备上生效。 2.仅在UIAbilityContext.startAbility中生效。 3.图片数据大小限制为600M。
startWindowBackgroundColor¹⁴⁺	string	否	是	在应用内启动UIAbility时，启动页所显示的背景颜色。如果未配置该字段，则默认采用module.json5文件中startWindowBackground字段的配置。约束： 1.该功能仅在2in1和tablet设备上生效。 2.仅在UIAbilityContext.startAbility中生效。
supportWindowModes¹⁴⁺	Array<bundleManager.SupportWindowMode>	否	是	在应用内启动UIAbility时，指定窗口是否显示最大化/窗口化/分屏按键。如果未配置该字段，则默认采用该UIAbility对应的module.json5配置文件中abilities标签的supportWindowMode字段取值。 - FULL_SCREEN：支持全屏模式。 - FLOATING：支持悬浮窗模式。 - SPLIT：支持分屏模式。通常需要配合FULL_SCREEN或FLOATING一起使用，不建议只配置SPLIT。当仅配置SPLIT时，2in1设备上的窗口默认为悬浮窗模式，支持进入分屏模式；tablet设备上的窗口默认为全屏模式，支持进入分屏模式。约束：该功能仅在2in1和tablet设备上生效。
minWindowWidth¹⁸⁺	number	否	是	窗口最小的宽度，单位为vp。约束：仅在2in1设备上生效。
minWindowHeight¹⁸⁺	number	否	是	窗口最小的高度，单位为vp。约束：仅在2in1设备上生效。
maxWindowWidth¹⁸⁺	number	否	是	窗口最大的宽度，单位为vp。约束：仅在2in1设备上生效。
maxWindowHeight¹⁸⁺	number	否	是	窗口最大的高度，单位为vp。约束：仅在2in1设备上生效。

示例：

import { UIAbility, Want, StartOptions, bundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };

    let color = new ArrayBuffer(0);
    let imagePixelMap: image.PixelMap;
    image.createPixelMap(color, {
      size: {
        height: 100,
        width: 100
      }
    }).then((data) => {
      imagePixelMap = data;
      let options: StartOptions = {
        displayId: 0,
        startWindowIcon: imagePixelMap,
        startWindowBackgroundColor: '#00000000',
        supportWindowModes: [
          bundleManager.SupportWindowMode.FULL_SCREEN,
          bundleManager.SupportWindowMode.SPLIT,
          bundleManager.SupportWindowMode.FLOATING
        ],
        minWindowWidth: 320,
        minWindowHeight: 240,
        maxWindowWidth: 2560,
        maxWindowHeight: 2560
      };

      try {
        this.context.startAbility(want, options, (err: BusinessError) => {
          if (err.code) {
            // 处理业务逻辑错误
            console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
            return;
          }
          // 执行正常业务
          console.info('startAbility succeed');
        });
      } catch (err) {
        // 处理入参错误异常
        let code = (err as BusinessError).code;
        let message = (err as BusinessError).message;
        console.error(`startAbility failed, code is ${code}, message is ${message}`);
      }
    }).catch((err: BusinessError) => {
      console.error(`createPixelMap failed, code is ${err.code}, message is ${err.message}`);
    });
  }
}