1# @ohos.app.ability.wantAgent (WantAgent模块)(系统接口) 2 3app.ability.WantAgent模块提供了创建WantAgent实例、获取实例的用户ID、获取want信息、比较WantAgent实例和获取bundle名称等能力。该模块将会取代[@ohos.wantAgent](js-apis-wantAgent.md)模块，建议优先使用本模块。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.app.ability.wantAgent (WantAgent模块)](js-apis-app-ability-wantAgent.md)。 10 11## 导入模块 12 13```ts 14import { WantAgent } from '@kit.AbilityKit'; 15``` 16 17## WantAgent.getWant 18 19getWant(agent: WantAgent, callback: AsyncCallback\<Want\>): void 20 21获取WantAgent对象的want（callback形式）。 22 23**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 24 25**系统接口**：此接口为系统接口。 26 27**参数：** 28 29| 参数名 | 类型 | 必填 | 说明 | 30| -------- | --------------------- | ---- | ------------------------------- | 31| agent | WantAgent | 是 | WantAgent对象。 | 32| callback | AsyncCallback\<[Want](js-apis-app-ability-want.md)\> | 是 | 获取WantAgent对象want的回调方法。 | 33 34**错误码：** 35 36以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 37 38| 错误码ID | 错误信息 | 39|-----------|--------------------| 40| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 41| 16000007 | Service busy. There are concurrent tasks. Try again later. | 42| 16000015 | Service timeout.| 43| 16000151 | Invalid wantagent object.| 44 45**示例：** 46 47```ts 48import { wantAgent, WantAgent as _WantAgent, Want } from '@kit.AbilityKit'; 49import { BusinessError } from '@kit.BasicServicesKit'; 50 51//wantAgent对象 52let wantAgentData: _WantAgent; 53//WantAgentInfo对象 54let wantAgentInfo: wantAgent.WantAgentInfo = { 55 wants: [ 56 { 57 deviceId: 'deviceId', 58 bundleName: 'com.example.myapplication', 59 abilityName: 'EntryAbility', 60 action: 'action1', 61 entities: ['entity1'], 62 type: 'MIMETYPE', 63 uri: 'key={true,true,false}', 64 parameters: 65 { 66 mykey0: 2222, 67 mykey1: [1, 2, 3], 68 mykey2: '[1, 2, 3]', 69 mykey3: 'ssssssssssssssssssssssssss', 70 mykey4: [false, true, false], 71 mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'], 72 mykey6: true, 73 } 74 } as Want 75 ], 76 actionType: wantAgent.OperationType.START_ABILITIES, 77 requestCode: 0, 78 wantAgentFlags:[wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 79}; 80 81//getWantAgent回调 82function getWantAgentCallback(err: BusinessError, data: _WantAgent) { 83 if (err) { 84 console.info(`getWantAgent failed, code: ${err.code}, message: ${err.message}`); 85 } else { 86 wantAgentData = data; 87 } 88 //getWant回调 89 let getWantCallback = (err: BusinessError, data: Want) => { 90 if(err) { 91 console.error(`getWant failed, code: ${err.code}, messgae: ${err.message}.`); 92 } else { 93 console.info(`getWant success, data: ${JSON.stringify(data)}.`); 94 } 95 } 96 try { 97 wantAgent.getWant(wantAgentData, getWantCallback); 98 } catch(err) { 99 let code = (err as BusinessError).code; 100 let msg = (err as BusinessError).message; 101 console.error(`getWant failed, code: ${code}, message: ${msg}.`); 102 } 103} 104 105try { 106 wantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback); 107} catch(err) { 108 let code = (err as BusinessError).code; 109 let msg = (err as BusinessError).message; 110 console.error(`getWantAgent failed, code: ${code}, message: ${msg}.`); 111} 112``` 113 114 115 116## WantAgent.getWant 117 118getWant(agent: WantAgent): Promise\<Want\> 119 120获取WantAgent对象的want（Promise形式）。 121 122**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 123 124**系统接口**：此接口为系统接口。 125 126**参数：** 127 128| 参数名 | 类型 | 必填 | 说明 | 129| ----- | --------- | ---- | ------------- | 130| agent | WantAgent | 是 | WantAgent对象。 | 131 132**返回值：** 133 134| 类型 | 说明 | 135| ----------------------------------------------------------- | ------------------------------------------------------------ | 136| Promise\<[Want](js-apis-app-ability-want.md)\> | 以Promise形式返回获取WantAgent对象的want。 | 137 138**错误码：** 139 140以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 141 142| 错误码ID | 错误信息 | 143|-----------|--------------------| 144| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 145| 16000007 | Service busy. There are concurrent tasks. Try again later. | 146| 16000015 | Service timeout.| 147| 16000151 | Invalid wantagent object.| 148 149错误码详细介绍请参考[元能力子系统错误码](errorcode-ability.md) 150 151**示例：** 152 153```ts 154import { wantAgent, WantAgent as _WantAgent, Want } from '@kit.AbilityKit'; 155import { BusinessError } from '@kit.BasicServicesKit'; 156 157//wantAgent对象 158let wantAgentData: _WantAgent; 159//WantAgentInfo对象 160let wantAgentInfo: wantAgent.WantAgentInfo = { 161 wants: [ 162 { 163 deviceId: 'deviceId', 164 bundleName: 'com.example.myapplication', 165 abilityName: 'EntryAbility', 166 action: 'action1', 167 entities: ['entity1'], 168 type: 'MIMETYPE', 169 uri: 'key={true,true,false}', 170 parameters: 171 { 172 mykey0: 2222, 173 mykey1: [1, 2, 3], 174 mykey2: '[1, 2, 3]', 175 mykey3: 'ssssssssssssssssssssssssss', 176 mykey4: [false, true, false], 177 mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'], 178 mykey6: true, 179 } 180 } as Want 181 ], 182 actionType: wantAgent.OperationType.START_ABILITIES, 183 requestCode: 0, 184 wantAgentFlags:[wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 185}; 186 187//getWantAgent回调 188function getWantAgentCallback(err: BusinessError, data: _WantAgent) { 189 if (err) { 190 console.info(`getWantAgent failed, code: ${err.code}, message: ${err.message}`); 191 } else { 192 wantAgentData = data; 193 } 194 try { 195 wantAgent.getWant(wantAgentData).then((data)=>{ 196 console.info(`getWant success, data: ${JSON.stringify(data)}`); 197 }).catch((err: BusinessError)=>{ 198 console.error(`getWant failed, code: ${err.code}, messgae: ${err.message}.`); 199 }); 200 } catch(err){ 201 let code = (err as BusinessError).code; 202 let msg = (err as BusinessError).message; 203 console.error(`getWant failed, code: ${code}, messgae: ${msg}.`); 204 } 205} 206 207try { 208 wantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback); 209} catch(err) { 210 let code = (err as BusinessError).code; 211 let msg = (err as BusinessError).message; 212 console.error(`getWantAgent failed, code: ${code}, messgae: ${msg}.`); 213} 214``` 215 216## WantAgent.setWantAgentMultithreading<sup>18+</sup> 217 218setWantAgentMultithreading(isMultithreadingSupported: boolean) : void 219 220开启或者关闭WantAgent多线程传递功能。 221 222**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 223 224**系统接口**：此接口为系统接口。 225 226**参数**： 227 228| 参数名 | 类型 | 必填 | 说明 | 229| ---------- | --------------------- | ---- | ------------------------------- | 230| isMultithreadingSupported | boolean | 是 |表示是否开启多线程传递功能。true表示开启，false表示关闭。 | 231 232**错误码**： 233 234以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 235 236| 错误码ID | 错误信息 | 237|-----------|--------------------| 238| 202 | Not system app. Interface caller is not a system app. | 239| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 240 241**示例**： 242 243```ts 244import { wantAgent, WantAgent as _WantAgent, Want } from '@kit.AbilityKit'; 245import { BusinessError } from '@kit.BasicServicesKit'; 246 247// 定义wantAgent对象 248let wantAgentData: _WantAgent; 249// 定义WantAgentInfo对象 250let wantAgentInfo: wantAgent.WantAgentInfo = { 251 wants: [ 252 { 253 deviceId: 'deviceId', 254 bundleName: 'com.example.myapplication', 255 abilityName: 'EntryAbility', 256 action: 'action1', 257 entities: ['entity1'], 258 type: 'MIMETYPE', 259 uri: 'key={true,true,false}', 260 parameters: 261 { 262 mykey0: 2222, 263 mykey1: [1, 2, 3], 264 mykey2: '[1, 2, 3]', 265 mykey3: 'ssssssssssssssssssssssssss', 266 mykey4: [false, true, false], 267 mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'], 268 mykey6: true, 269 } 270 } as Want 271 ], 272 actionType: wantAgent.OperationType.START_ABILITIES, 273 requestCode: 0, 274 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 275}; 276 277// 定义getWantAgent回调 278function getWantAgentCallback(err: BusinessError, data: _WantAgent) { 279 if (err) { 280 console.info(`Failed to call getWantAgentCallback. Code is ${err.code}. Message is ${err.message}.`); 281 } else { 282 wantAgentData = data; 283 } 284 285 try { 286 wantAgent.setWantAgentMultithreading(true); 287 } catch (err) { 288 console.error(`Failed to set wantAgentMultithreading. Code is ${err.code}. Message is ${err.message}.`); 289 } 290} 291 292try { 293 wantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback); 294} catch (err) { 295 console.error(`Failed to get wantAgent. Code is ${err.code}. Message is ${err.message}.`); 296} 297``` 298 299## OperationType 300 301表示操作WantAgent类型的枚举。 302 303**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 304 305| 名称 | 值 | 说明 | 306|-------------------------|---|-----------------------------------------------| 307| START_SERVICE_EXTENSION<sup>12+</sup> | 6 | 开启一个ServiceExtension。<br/>**系统接口**：该接口为系统接口。 |