@ohos.app.ability.Want (Want)

Want is a carrier for information transfer between objects (application components). Want can be used as a parameter of startAbility to specify a startup target and information that needs to be carried during startup, for example, bundleName and abilityName, which respectively indicate the bundle name of the target ability and the ability name in the bundle. When UIAbilityA needs to start UIAbilityB and transfer some data to UIAbilityB, it can use Want a carrier to transfer the data.

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.

Modules to Import

import Want from '@ohos.app.ability.Want';

Attributes

System capability: SystemCapability.Ability.AbilityBase

Example

• Basic usage: called in a UIAbility object, as shown in the example below. For details about how to obtain the context, see Obtaining the Context of UIAbility.

  import common from '@ohos.app.ability.common';
  import Want from '@ohos.app.ability.Want';
  import { BusinessError } from '@ohos.base';
  
  let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
  let want: Want = {
    deviceId: '', // An empty deviceId indicates the local device.
    bundleName: 'com.example.myapplication',
    abilityName: 'FuncAbility',
    moduleName: 'entry', // moduleName is optional.
  };
  
  context.startAbility(want, (err: BusinessError) => {
    if (err.code) {
      // Start an ability explicitly. The bundleName, abilityName, and moduleName parameters work together to uniquely identify an ability.
      console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
    }
  });
  

• Currently, the following data types are supported: string, number, Boolean, object, array, and file descriptor (FD).

  • String

    import common from '@ohos.app.ability.common';
    import Want from '@ohos.app.ability.Want';
    import { BusinessError } from '@ohos.base';
    
    let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'FuncAbility',
      parameters: {
        keyForString: 'str',
      },
    };
    
    context.startAbility(want, (err: BusinessError) => {
      if (err.code) {
        console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
      }
    });
    

  • Number

    import common from '@ohos.app.ability.common';
    import Want from '@ohos.app.ability.Want';
    import { BusinessError } from '@ohos.base';
    
    let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'FuncAbility',
      parameters: {
        keyForInt: 100,
        keyForDouble: 99.99,
      },
    };
    
    context.startAbility(wan, (err) => {
      console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
    });
    

  • Boolean

    import common from '@ohos.app.ability.common';
    import Want from '@ohos.app.ability.Want';
    import { BusinessError } from '@ohos.base';
    
    let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'FuncAbility',
      parameters: {
        keyForBool: true,
      },
    };
    
    context.startAbility(want, (err: BusinessError) => {
      if (err.code) {
        console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
      }
    });
    

  • Object

    import common from '@ohos.app.ability.common';
    import Want from '@ohos.app.ability.Want';
    import { BusinessError } from '@ohos.base';
    
    let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'FuncAbility',
      parameters: {
        keyForObject: {
          keyForObjectString: 'str',
          keyForObjectInt: -200,
          keyForObjectDouble: 35.5,
          keyForObjectBool: false,
        },
      },
    };
    
    context.startAbility(want, (err: BusinessError) => {
      if (err.code) {
        console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
      }
    });
    

  • Array

    import common from '@ohos.app.ability.common';
    import Want from '@ohos.app.ability.Want';
    import { BusinessError } from '@ohos.base';
    
    let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'FuncAbility',
      parameters: {
        keyForArrayString: ['str1', 'str2', 'str3'],
        keyForArrayInt: [100, 200, 300, 400],
        keyForArrayDouble: [0.1, 0.2],
        keyForArrayObject: [{ obj1: 'aaa' }, { obj2: 100 }],
      },
    };
    
    context.startAbility(want, (err: BusinessError) => {
      if (err.code) {
        console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
      }
    });
    

  • FD

      import fs from '@ohos.file.fs';
      import common from '@ohos.app.ability.common';
      import Want from '@ohos.app.ability.Want';
      import { BusinessError } from '@ohos.base';
    
      let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
    
      let fd: number = 0;
      try {
        fd = fs.openSync('/data/storage/el2/base/haps/pic.png').fd;
      } catch(err) {
        let code = (err as BusinessError).code;
        let message = (err as BusinessError).message;
        console.error(`Failed to openSync. Code: ${code}, message: ${message}`);
      }
      let want: Want = {
        deviceId: '', // An empty deviceId indicates the local device.
        bundleName: 'com.example.myapplication',
        abilityName: 'FuncAbility',
        moduleName: 'entry', // moduleName is optional.
        parameters: {
          'keyFd': { 'type': 'FD', 'value': fd } // {'type':'FD', 'value':fd} is a fixed usage, indicating that the data is a file descriptor.
        }
      };
    
      context.startAbility(want, (err: BusinessError) => {
        if (err.code) {
          console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
        }
      });
    

  • Usage of parameter:

    The following uses ability.params.backToOtherMissionStack as an example. When a ServiceExtensionAbility starts a UIAbility, redirection back across mission stacks is supported.

      // (1) UIAbility1 starts a ServiceExtensionAbility.
      import common from '@ohos.app.ability.common';
      import Want from '@ohos.app.ability.Want';
      import { BusinessError } from '@ohos.base';
    
      let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
      let want: Want = {
        bundleName: 'com.example.myapplication1',
        abilityName: 'ServiceExtensionAbility',
      };
      context.startAbility(want, (err: BusinessError) => {
        if (err.code) {
          console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
        }
      });
    

      // (2) The ServiceExtensionAbility starts UIAbility2, carrying **"ability.params.backToOtherMissionStack": true** during the startup.
      import common from '@ohos.app.ability.common';
      import Want from '@ohos.app.ability.Want';
      import { BusinessError } from '@ohos.base';
    
      let context = getContext(this) as common.ServiceExtensionContext; // ServiceExtensionContext
      let want: Want = {
        bundleName: 'com.example.myapplication2',
        abilityName: 'MainAbility',
        parameters: {
          "ability.params.backToOtherMissionStack": true,
        },
      };
    
      context.startAbility(want, (err: BusinessError) => {
        if (err.code) {
          console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
        }
      });
    

    NOTE

    In the preceding example, when the ServiceExtensionAbility starts UIAbility2, "ability.params.backToOtherMissionStack": true is carried, indicating that redirection back across mission stacks is supported. Therefore, when you press Back on the page of UIAbility2, the page of UIAbility1 page is displayed. However, if ability.params.backToOtherMissionStack is not carried or if "ability.params.backToOtherMissionStack": false is carried, the page of UIAbility1 is not displayed when you press Back on the page of UIAbility2.

    parameter carries customized parameters. It is transferred by UIAbilityA to UIAbilityB and obtained from UIAbilityB.

      //(1) UIAbilityA calls startAbility to start UIAbilityB.
      import common from '@ohos.app.ability.common';
      import Want from '@ohos.app.ability.Want';
      import { BusinessError } from '@ohos.base';
    
      let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
      let want: Want = {
        bundleName: 'com.example.myapplication',
        abilityName: 'UIAbilityB',
        parameters: {
          developerParameters: 'parameters',
        },
      };
      context.startAbility(want, (err: BusinessError) => {
        if (err.code) {
          console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
        }
      });
    

      // (2) If the UIAbilityB instance is started for the first time, it enters the onCreate lifecycle.
      import UIAbility from '@ohos.app.ability.UIAbility';
      import AbilityConstant from '@ohos.app.ability.AbilityConstant';
      import Want from '@ohos.app.ability.Want';
    
      class UIAbilityB extends UIAbility {
        onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
          console.log(`onCreate, want parameters: ${want.parameters?.developerParameters}`);
        }
      }