harmony 鸿蒙@ohos.app.ability.StartOptions (StartOptions)

2025-06-12
浏览 (6)

@ohos.app.ability.StartOptions (StartOptions)

StartOptions is used as an input parameter of startAbility() to specify the window mode of an ability.

NOTE

The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.

The APIs of this module can be used only in the stage model.

Modules to Import

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

Properties

System capability: SystemCapability.Ability.AbilityRuntime.Core

Name	Type	Read-only	Optional	Description
windowMode¹²⁺	number	No	Yes	Window mode when the ability is started. For details, see WindowMode.
displayId	number	No	Yes	Display ID mode. The default value is 0, indicating the current display. Atomic service API: This API can be used in atomic services since API version 11.
withAnimation¹¹⁺	boolean	No	Yes	Whether animation effects are used when the ability is started. The value true means that animation effects are used, and false means the opposite. Constraints: 1. This property takes effect only on 2-in-1 devices and tablets. 2. The caller and target must be the same application.
windowLeft¹¹⁺	number	No	Yes	Position of the left edge of the window, in px. The value range is [0, maxWindowWidth]. If a negative value is passed, the system will default to 0. When configuring this field, you are advised to also configure windowTop.
windowTop¹¹⁺	number	No	Yes	Position of the top edge of the window, in px. The value range is [0, maxWindowHeight]. If a negative value is passed, the system will default to 0. When configuring this field, you are advised to also configure windowLeft.
windowWidth¹¹⁺	number	No	Yes	Window width, in px. The value range is [minWindowWidth, maxWindowWidth].
windowHeight¹¹⁺	number	No	Yes	Window height, in px. The value range is [minWindowHeight, maxWindowHeight].
processMode¹²⁺	contextConstant.ProcessMode	No	Yes	Process mode. Constraints: 1. This property takes effect only on 2-in-1 devices and tablets. 2. This property takes effect only in UIAbilityContext.startAbility. 3. processMode and startupVisibility must be set in pair.
startupVisibility¹²⁺	contextConstant.StartupVisibility	Yes	No	Visibility of the ability after it is started. Constraints: 1. This property takes effect only on 2-in-1 devices and tablets. 2. This property takes effect only in UIAbilityContext.startAbility. 3. processMode and startupVisibility must be set in pair.
startWindowIcon¹⁴⁺	image.PixelMap	No	Yes	Icon displayed on the launch page when the UIAbility is started in an application. If this property is not set, the value of startWindowIcon in the module.json5 file is used by default. Constraints: 1. This property takes effect only on 2-in-1 devices and tablets. 2. This property takes effect only in UIAbilityContext.startAbility. 3. The maximum size of an image is 600 MB.
startWindowBackgroundColor¹⁴⁺	string	No	Yes	Background color of the launch page when the UIAbility is launched in an application. The value is in ARGB format, for example, #E5FFFFFF. If this property is not set, the value of startWindowBackground in the module.json5 file is used by default. Constraints: 1. This property takes effect only on 2-in-1 devices and tablets. 2. This property takes effect only in UIAbilityContext.startAbility.
supportWindowModes¹⁴⁺	Array<bundleManager.SupportWindowMode>	No	Yes	Whether to display the maximize, minimize, or split-screen button when the UIAbility is launched in an application. If this property is not set, the value of supportWindowMode configured under abilities in the module.json5 file corresponding to the UIAbility is used by default. - FULL_SCREEN: full-screen mode. - FLOATING: floating window mode. - SPLIT: split-screen mode. Generally, FULL_SCREEN or FLOATING must be used together. You are not advised to configure only SPLIT. If only SPLIT is configured, the window on 2-in-1 devices is in floating window mode by default and can transition to the split-screen mode, and the window on tablets is in full-screen mode by default and can transition to the split-screen mode. Constraints: This property takes effect only on 2-in-1 devices and tablets.
minWindowWidth¹⁷⁺	number	No	Yes	Minimum width of the window, in px. You can call getWindowLimits to obtain the size limit of the current window. Constraints: It takes effect only on 2-in-1 devices and tablets.
minWindowHeight¹⁷⁺	number	No	Yes	Minimum height of the window, in px. You can call getWindowLimits to obtain the size limit of the current window. Constraints: It takes effect only on 2-in-1 devices and tablets.
maxWindowWidth¹⁷⁺	number	No	Yes	Maximum width of the window, in px. You can call getWindowLimits to obtain the size limit of the current window. Constraints: It takes effect only on 2-in-1 devices and tablets.
maxWindowHeight¹⁷⁺	number	No	Yes	Maximum height of the window, in px. You can call getWindowLimits to obtain the size limit of the current window. Constraints: It takes effect only on 2-in-1 devices and tablets.
completionHandler²⁰⁺	CompletionHandler	No	Yes	Class for handling the results of application launching requests.

Example

  import { UIAbility, Want, StartOptions, bundleManager, CompletionHandler } 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 completionHandler: CompletionHandler = {
        onRequestSuccess: (elementName: bundleManager.ElementName, message: string): void => {
          console.log(`${elementName.bundleName}-${elementName.moduleName}-${elementName.abilityName} start succeeded: ${message}`);
        },
        onRequestFailure: (elementName: bundleManager.ElementName, message: string): void => {
          console.log(`${elementName.bundleName}-${elementName.moduleName}-${elementName.abilityName} start failed: ${message}`);
        }
      };

      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,
          completionHandler: completionHandler
        };

        try {
          this.context.startAbility(want, options, (err: BusinessError) => {
            if (err.code) {
              // Process service logic errors.
              console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
              return;
            }
            // Carry out normal service processing.
            console.info('startAbility succeed');
          });
        } catch (err) {
          // Process input parameter errors.
          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}`);
      });
    }
  }