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 UIAbility A needs to start UIAbility B and transfer some data to UIAbility B, 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 '@ohos.app.ability.Want'; 13``` 14 15## Attributes 16 17**System capability**: SystemCapability.Ability.AbilityBase 18 19| Name | Type | Mandatory| Description | 20| ----------- | -------------------- | ---- | ------------------------------------------------------------ | 21| deviceId | string | No | ID of the device running the ability. If this field is unspecified, the local device is used. | 22| bundleName | string | No | Bundle name of the ability.| 23| moduleName | string | No| Name of the module to which the ability belongs.| 24| 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.| 25| 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). | 26| 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.| 27| 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**.| 28| 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.| 29| parameters | {[key: string]: any} | No | Want parameters in the form of custom key-value (KV) pairs. By default, the following keys are carried:<br>- **ohos.aafwk.callerPid**: PID of the caller.<br>- **ohos.aafwk.param.callerBundleName**: bundle name of the caller.<br>- **ohos.aafwk.param.callerToken**: token of the caller.<br>- **ohos.aafwk.param.callerUid**: UID in [BundleInfo](js-apis-bundleManager-bundleInfo.md#bundleinfo-1), that is, the application UID in the bundle information.<br>- **component.startup.newRules**: whether to enable the new control rule.<br>- **moduleName**: module name of the caller. No matter what this field is set to, the correct module name will be sent to the peer.<br>- **ohos.dlp.params.sandbox**: available only for DLP files.<br>- **ability.params.backToOtherMissionStack**: whether to support redirection back across mission stacks.| 30| [flags](js-apis-ability-wantConstant.md#wantconstantflags) | 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.| 31 32**Example** 33 34- 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). 35 36 ```ts 37 import common from '@ohos.app.ability.common'; 38 import Want from '@ohos.app.ability.Want'; 39 40 let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext 41 let want: Want = { 42 deviceId: '', // An empty deviceId indicates the local device. 43 bundleName: 'com.example.myapplication', 44 abilityName: 'FuncAbility', 45 moduleName: 'entry', // moduleName is optional. 46 }; 47 48 context.startAbility(want, (err) => { 49 // Start an ability explicitly. The bundleName, abilityName, and moduleName parameters work together to uniquely identify an ability. 50 console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`); 51 }); 52 ``` 53 54- Currently, the following data types are supported: string, number, Boolean, object, array, and file descriptor (FD). 55 56 * String 57 ```ts 58 import common from '@ohos.app.ability.common'; 59 import Want from '@ohos.app.ability.Want'; 60 61 let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext 62 let want: Want = { 63 bundleName: 'com.example.myapplication', 64 abilityName: 'FuncAbility', 65 parameters: { 66 keyForString: 'str', 67 }, 68 }; 69 70 context.startAbility(want, (err) => { 71 console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`); 72 }); 73 ``` 74 * Number 75 ```ts 76 import common from '@ohos.app.ability.common'; 77 import Want from '@ohos.app.ability.Want'; 78 79 let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext 80 let want: Want = { 81 bundleName: 'com.example.myapplication', 82 abilityName: 'FuncAbility', 83 parameters: { 84 keyForInt: 100, 85 keyForDouble: 99.99, 86 }, 87 }; 88 89 context.startAbility(want, (err) => { 90 console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`); 91 }); 92 ``` 93 * Boolean 94 ```ts 95 import common from '@ohos.app.ability.common'; 96 import Want from '@ohos.app.ability.Want'; 97 98 let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext 99 let want: Want = { 100 bundleName: 'com.example.myapplication', 101 abilityName: 'FuncAbility', 102 parameters: { 103 keyForBool: true, 104 }, 105 }; 106 107 context.startAbility(want, (err) => { 108 console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`); 109 }); 110 ``` 111 * Object 112 ```ts 113 import common from '@ohos.app.ability.common'; 114 import Want from '@ohos.app.ability.Want'; 115 116 let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext 117 let want: Want = { 118 bundleName: 'com.example.myapplication', 119 abilityName: 'FuncAbility', 120 parameters: { 121 keyForObject: { 122 keyForObjectString: 'str', 123 keyForObjectInt: -200, 124 keyForObjectDouble: 35.5, 125 keyForObjectBool: false, 126 }, 127 }, 128 }; 129 130 context.startAbility(want, (err) => { 131 console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`); 132 }); 133 ``` 134 * Array 135 ```ts 136 import common from '@ohos.app.ability.common'; 137 import Want from '@ohos.app.ability.Want'; 138 139 let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext 140 let want: Want = { 141 bundleName: 'com.example.myapplication', 142 abilityName: 'FuncAbility', 143 parameters: { 144 keyForArrayString: ['str1', 'str2', 'str3'], 145 keyForArrayInt: [100, 200, 300, 400], 146 keyForArrayDouble: [0.1, 0.2], 147 keyForArrayObject: [{ obj1: 'aaa' }, { obj2: 100 }], 148 }, 149 }; 150 151 context.startAbility(want, (err) => { 152 console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`); 153 }); 154 ``` 155 * FD 156 ```ts 157 import fs from '@ohos.file.fs'; 158 import common from '@ohos.app.ability.common'; 159 import Want from '@ohos.app.ability.Want'; 160 import { BusinessError } from '@ohos.base'; 161 162 let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext 163 164 let fd: number = 0; 165 try { 166 fd = fs.openSync('/data/storage/el2/base/haps/pic.png').fd; 167 } catch(err) { 168 let code = (err as BusinessError).code; 169 let message = (err as BusinessError).message; 170 console.error(`Failed to openSync. Code: ${code}, message: ${message}`); 171 } 172 let want: Want = { 173 deviceId: '', // An empty deviceId indicates the local device. 174 bundleName: 'com.example.myapplication', 175 abilityName: 'FuncAbility', 176 moduleName: 'entry', // moduleName is optional. 177 parameters: { 178 'keyFd': { 'type': 'FD', 'value': fd } // {'type':'FD', 'value':fd} is a fixed usage, indicating that the data is a file descriptor. 179 } 180 }; 181 182 context.startAbility(want, (err) => { 183 console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`); 184 }); 185 ``` 186 - Usage of **parameters**: The following uses **ability.params.backToOtherMissionStack** as an example. When a ServiceExtensionAbility starts a UIAbility, redirection back across mission stacks is supported. 187 188 ```ts 189 // (1) UIAbility1 starts a ServiceExtensionAbility. 190 import common from '@ohos.app.ability.common'; 191 import Want from '@ohos.app.ability.Want'; 192 193 let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext 194 let want: Want = { 195 bundleName: 'com.example.myapplication1', 196 abilityName: 'ServiceExtensionAbility', 197 }; 198 context.startAbility(want, (err) => { 199 console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`); 200 }); 201 ``` 202 203 ```ts 204 // (2) The ServiceExtensionAbility starts UIAbility2, carrying **"ability.params.backToOtherMissionStack": true** during the startup. 205 import common from '@ohos.app.ability.common'; 206 import Want from '@ohos.app.ability.Want'; 207 208 let context = getContext(this) as common.ServiceExtensionContext; // ServiceExtensionContext 209 let want: Want = { 210 bundleName: 'com.example.myapplication2', 211 abilityName: 'MainAbility', 212 parameters: { 213 "ability.params.backToOtherMissionStack": true, 214 }, 215 }; 216 217 context.startAbility(want, (err) => { 218 console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`); 219 }); 220 ``` 221 222 > **NOTE** 223 > 224 > 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 UIAbility 2, 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 UIAbility 2. 225
