1# @ohos.app.ability.Want (Want)
2
3Want 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.
4
5> **NOTE**
6>
7> 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.
8
9## Modules to Import
10
11```ts
12import { Want } from '@kit.AbilityKit';
13```
14
15## Properties
16
17**Atomic service API**: This API can be used in atomic services since API version 11.
18
19**System capability**: SystemCapability.Ability.AbilityBase
20
21| Name       | Type                | Mandatory| Description                                                        |
22| ----------- | -------------------- | ---- | ------------------------------------------------------------ |
23| deviceId    | string               | No  | ID of the device running the ability. If this field is unspecified, the local device is used.                               |
24| bundleName   | string               | No  | Bundle name of the ability.|
25| moduleName | string | No| Name of the module to which the ability belongs.|
26| abilityName  | string               | No  | Name of the ability. If both **bundleName** and **abilityName** are specified in a **Want** object, the **Want** object can match a specific ability. The value of **abilityName** must be unique in an application.|
27| action | string               | No  | Action to take, such as viewing and sharing application details. In implicit Want, you can define this field and use it together with **uri** or **parameters** to specify the operation to be performed on the data. For details about the definition and matching rules of implicit Want, see [Matching Rules of Explicit Want and Implicit Want](../../application-models/explicit-implicit-want-mappings.md).            |
28| entities | Array\<string> | No| Additional category information (such as browser and video player) of the ability. It is a supplement to the **action** field for implicit Want. and is used to filter ability types.|
29| uri | string | No| Data carried. This field is used together with **type** to specify the data type. If **uri** is specified in a Want, the Want will match the specified URI information, including **scheme**, **schemeSpecificPart**, **authority**, and **path**.|
30| type | string | No| MIME type, that is, the type of the file to open, for example, **'text/xml'** and **'image/*'**. For details about the MIME type definition, see https://www.iana.org/assignments/media-types/media-types.xhtml?utm_source=ld246.com.|
31| parameters   | Record\<string, Object> | No  | List of parameters in the **Want** object.<br>1. The values of the following keys are assigned by the system. Manual settings do not take effect, since the system automatically changes the values to the actual values during data transfer.<br>- **ohos.aafwk.param.callerPid**: PID of the caller. The value is a string.<br>- **ohos.aafwk.param.callerBundleName**: bundle name of the caller. The value is a string.<br>- **ohos.aafwk.param.callerAbilityName**: ability name of the caller. The value is a string.<br>- **ohos.aafwk.param.callerNativeName**: process name of the caller when the native method is called. The value is a string.<br>- **ohos.aafwk.param.callerAppId**: appId of the caller. The value is a string.<br>- **ohos.aafwk.param.callerAppIdentifier**: appIdentifier of the caller. The value is a string.<br>- **ohos.aafwk.param.callerToken**: token of the caller. The value is a string.<br>- **ohos.aafwk.param.callerUid**: UID in [BundleInfo](js-apis-bundleManager-bundleInfo.md#bundleinfo-1), that is, the application's UID in the bundle information. The value is a number.<br>- **ohos.param.callerAppCloneIndex**: clone index of the caller. The value is of the numeric type.<br>- **component.startup.newRules**: enabled status of the new control rule. The value is of the Boolean type.<br>- **moduleName**: module name of the caller. The value is a string.<br>- **ability.params.backToOtherMissionStack**: support for redirection back across mission stacks. The value is of the Boolean type.<br>- **ohos.ability.params.abilityRecoveryRestart**: support for ability restart upon fault recovery. The value is of the Boolean type.<br>- **ohos.extra.param.key.contentTitle**: title that can be shared by the atomic service. The value is a string.<br>- **ohos.extra.param.key.shareAbstract**: content that can be shared by the atomic service. The value is a string.<br>- **ohos.extra.param.key.shareUrl**: URL of the content that can be shared by the atomic service. The value is a string.<br>- **ohos.extra.param.key.supportContinuePageStack**: support for migration of page stack information during cross-device migration. The value is of the Boolean type. The default value is **true**, indicating that page stack information is automatically migrated.<br>- **ohos.extra.param.key.supportContinueSourceExit**: support for application exit on the source device during cross-device migration. The value is of the Boolean type. The default value is **true**, indicating that the application on the source device automatically exits.<br>- **ohos.extra.param.key.showMode**: mode to show the atomic service startup. The value is an enumerated value of [wantConstant.ShowMode](js-apis-app-ability-wantConstant.md#showmode12).<br>- **ohos.dlp.params.sandbox**: available only for DLP files. This key is involved only in system applications.<br>- **ohos.dlp.params.bundleName**: bundle name of DLP. The value is a string. This key is involved only in system applications.<br>- **ohos.dlp.params.moduleName**: module name of DLP. The value is a string. This key is involved only in system applications.<br>- **ohos.dlp.params.abilityName**: ability name of DLP. The value is a string. This key is involved only in system applications.<br>- **ohos.dlp.params.index**: DLP index. The value is a number. This key is involved only in system applications.<br>- **ohos.ability.params.asssertFaultSessionId**: session ID of the fault assertion. The value is a string. This key is involved only in system applications.<br><br>2. The following keys are defined by the system, and their values need to be manually assigned.<br>- **ability.params.stream**: File URIs to be authorized to the target ability. The value is a file URI array of the string type.<br>- **ohos.extra.param.key.appCloneIndex**: index of the application clone.<br><br>3. In addition to the foregoing cases, applications may further agree on the key-value pairs to transfer.<br><br>**NOTE**<br>For details about the constants of **Params** in **want**, see [wantConstant](js-apis-app-ability-wantConstant.md).<br>Note that a maximum of 200 KB data that can be transferred by using **WantParams**. If the data volume exceeds 200 KB, transfer data in [WriteRawDataBuffer](../apis-ipc-kit/js-apis-rpc.md#writerawdatabuffer11) or [uri](../apis-arkts/js-apis-uri.md) mode.<br>The values of **parameters** must be of the following basic data types: String, Number, Boolean, Object, undefined, and null. Functions in an object cannot be transferred. |
32| [flags](js-apis-ability-wantConstant.md#flags) | number | No| How the **Want** object will be handled. By default, a number is passed in.<br>For example, **wantConstant.Flags.FLAG_ABILITY_CONTINUATION** specifies whether to start the ability in cross-device migration scenarios.|
33
34**Example**
35
36- 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](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability).
37
38  ```ts
39  import { common, Want } from '@kit.AbilityKit';
40  import { BusinessError } from '@kit.BasicServicesKit';
41
42  let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
43  let want: Want = {
44    deviceId: '', // An empty deviceId indicates the local device.
45    bundleName: 'com.example.myapplication',
46    abilityName: 'FuncAbility',
47    moduleName: 'entry', // moduleName is optional.
48  };
49
50  context.startAbility(want, (err: BusinessError) => {
51    if (err.code) {
52      // Start an ability explicitly. The bundleName, abilityName, and moduleName parameters work together to uniquely identify an ability.
53      console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
54    }
55  });
56  ```
57
58- Currently, the following data types are supported: string, number, Boolean, object, array, and file descriptor (FD).
59
60    * String
61        ```ts
62        import { common, Want } from '@kit.AbilityKit';
63        import { BusinessError } from '@kit.BasicServicesKit';
64
65        let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
66        let want: Want = {
67          bundleName: 'com.example.myapplication',
68          abilityName: 'FuncAbility',
69          parameters: {
70            keyForString: 'str',
71          },
72        };
73
74        context.startAbility(want, (err: BusinessError) => {
75          if (err.code) {
76            console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
77          }
78        });
79        ```
80    * Number
81        ```ts
82        import { common, Want } from '@kit.AbilityKit';
83
84        let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
85        let want: Want = {
86          bundleName: 'com.example.myapplication',
87          abilityName: 'FuncAbility',
88          parameters: {
89            keyForInt: 100,
90            keyForDouble: 99.99,
91          },
92        };
93
94        context.startAbility(want, (err) => {
95          if (err.code) {
96            console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
97          }
98        });
99        ```
100    * Boolean
101        ```ts
102        import { common, Want } from '@kit.AbilityKit';
103        import { BusinessError } from '@kit.BasicServicesKit';
104
105        let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
106        let want: Want = {
107          bundleName: 'com.example.myapplication',
108          abilityName: 'FuncAbility',
109          parameters: {
110            keyForBool: true,
111          },
112        };
113
114        context.startAbility(want, (err: BusinessError) => {
115          if (err.code) {
116            console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
117          }
118        });
119        ```
120    * Object
121        ```ts
122        import { common, Want } from '@kit.AbilityKit';
123        import { BusinessError } from '@kit.BasicServicesKit';
124
125        let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
126        let want: Want = {
127          bundleName: 'com.example.myapplication',
128          abilityName: 'FuncAbility',
129          parameters: {
130            keyForObject: {
131              keyForObjectString: 'str',
132              keyForObjectInt: -200,
133              keyForObjectDouble: 35.5,
134              keyForObjectBool: false,
135            },
136          },
137        };
138
139        context.startAbility(want, (err: BusinessError) => {
140          if (err.code) {
141            console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
142          }
143        });
144        ```
145    * Array
146
147        ```ts
148        import { common, Want } from '@kit.AbilityKit';
149        import { BusinessError } from '@kit.BasicServicesKit';
150
151        let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
152        let want: Want = {
153          bundleName: 'com.example.myapplication',
154          abilityName: 'FuncAbility',
155          parameters: {
156            keyForArrayString: ['str1', 'str2', 'str3'],
157            keyForArrayInt: [100, 200, 300, 400],
158            keyForArrayDouble: [0.1, 0.2],
159            keyForArrayObject: [{ obj1: 'aaa' }, { obj2: 100 }],
160          },
161        };
162
163        context.startAbility(want, (err: BusinessError) => {
164          if (err.code) {
165            console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
166          }
167        });
168        ```
169
170    * FD
171
172        ```ts
173        import { fileIo } from '@kit.CoreFileKit';
174        import { common, Want } from '@kit.AbilityKit';
175        import { BusinessError } from '@kit.BasicServicesKit';
176
177        let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
178        let fd: number = 0;
179
180        try {
181          fd = fileIo.openSync('/data/storage/el2/base/haps/pic.png').fd;
182        } catch(err) {
183          let code = (err as BusinessError).code;
184          let message = (err as BusinessError).message;
185          console.error(`Failed to openSync. Code: ${code}, message: ${message}`);
186        }
187        let want: Want = {
188          deviceId: '', // An empty deviceId indicates the local device.
189          bundleName: 'com.example.myapplication',
190          abilityName: 'FuncAbility',
191          moduleName: 'entry', // moduleName is optional.
192          parameters: {
193            'keyFd': { 'type': 'FD', 'value': fd } // {'type':'FD', 'value':fd} is a fixed usage, indicating that the data is a file descriptor.
194          }
195        };
196
197        context.startAbility(want, (err: BusinessError) => {
198          if (err.code) {
199            console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
200          }
201        });
202        ```
203
204- **parameter** usage: **parameter** carries custom parameters. It is transferred by UIAbilityA to UIAbilityB and obtained from UIAbilityB.
205
206        ```ts
207        // (1) UIAbilityA calls startAbility to start UIAbilityB.
208        import { common, Want } from '@kit.AbilityKit';
209        import { BusinessError } from '@kit.BasicServicesKit';
210
211        let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
212        let want: Want = {
213          bundleName: 'com.example.myapplication',
214          abilityName: 'UIAbilityB',
215          parameters: {
216            developerParameters: 'parameters',
217          },
218        };
219
220        context.startAbility(want, (err: BusinessError) => {
221          if (err.code) {
222            console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
223          }
224        });
225        ```
226
227        ```ts
228        // (2) If the UIAbilityB instance is started for the first time, it enters the onCreate lifecycle.
229        import { UIAbility, Want, AbilityConstant } from '@kit.AbilityKit';
230
231        class UIAbilityB extends UIAbility {
232          onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
233            console.log(`onCreate, want parameters: ${want.parameters?.developerParameters}`);
234          }
235        }
236        ```
237- Usage of the keys of [wantConstant](js-apis-app-ability-wantConstant.md) in **parameter**.
238
239        ```ts
240        import { common, Want, wantConstant } from '@kit.AbilityKit';
241        import { BusinessError } from '@kit.BasicServicesKit';
242
243        let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
244        let want: Want = {
245          bundleName: 'com.example.myapplication',
246          abilityName: 'FuncAbility',
247          parameters: {
248            [wantConstant.Params.CONTENT_TITLE_KEY]: 'contentTitle',
249          },
250        };
251
252        context.startAbility(want, (err: BusinessError) => {
253          if (err.code) {
254            console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
255          }
256        });
257        ```
258