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](js-apis-app-ability-wantAgent.md#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.error(`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}, message: ${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](js-apis-app-ability-wantAgent.md#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.error(`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}, message: ${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}, message: ${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}, message: ${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.error(`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## wantAgent.triggerAsync<sup>20+</sup> 300 301triggerAsync(agent: WantAgent, triggerInfo: TriggerInfo, context: Context): Promise\<CompleteData\> 302 303主动触发WantAgent实例，即按照WantAgent实例中已封装的指定操作和参数等信息执行。使用Promise异步回调。 304 305**需要权限**：ohos.permission.TRIGGER_LOCAL_WANTAGENT（仅当入参agent为本地WantAgent实例时需要申请） 306 307**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 308 309**系统接口**：此接口为系统接口。 310 311**参数：** 312 313| 参数名 | 类型 | 必填 | 说明 | 314| ----------- | ----------------------------- | ---- | ------------------------------- | 315| agent | [WantAgent](js-apis-app-ability-wantAgent.md#wantagent) | 是 | WantAgent对象。 | 316| triggerInfo | [TriggerInfo](js-apis-inner-wantAgent-triggerInfo.md) | 是 | TriggerInfo对象。 | 317| context | [Context](js-apis-inner-application-context.md) | 是 | 请求触发WantAgent的UIAbility/ExtensionAbility的Context。| 318 319**返回值：** 320 321| 类型 | 说明 | 322| ----------------------------------------------------------- | ------------------------------------------------------------ | 323| Promise\<[CompleteData](js-apis-app-ability-wantAgent.md#completedata)\> | 以Promise形式返回主动激发WantAgent获得的数据。 | 324 325**错误码：** 326 327以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 328 329| 错误码ID | 错误信息 | 330|-----------|--------------------| 331| 201 | Permission verification failed. The application does not have the permission required to call the API. | 332| 202 | The application is not system-app, can not use system-api. | 333| 16000020 | The context is not ability context. | 334| 16000151 | Invalid wantAgent object.| 335| 16000153 | The WantAgent has been canceled.| 336 337**示例：** 338 339```ts 340import { wantAgent, Want, UIAbility, AbilityConstant } from '@kit.AbilityKit'; 341import type { WantAgent } from '@kit.AbilityKit'; 342import { BusinessError } from '@kit.BasicServicesKit'; 343 344// wantAgent对象 345let wantAgentData: WantAgent; 346// triggerInfo 347let triggerInfo: wantAgent.TriggerInfo = { 348 code: 0 // 自定义结果码 349}; 350// WantAgentInfo对象 351let wantAgentInfo: wantAgent.WantAgentInfo = { 352 // 自定义参数 353 wants: [ 354 { 355 deviceId: 'deviceId', 356 bundleName: 'com.example.myapplication', 357 abilityName: 'EntryAbility', 358 action: 'action1', 359 entities: ['entity1'], 360 type: 'MIMETYPE', 361 uri: 'key={true,true,false}', 362 parameters: 363 { 364 mykey0: 2222, 365 mykey1: [1, 2, 3], 366 mykey2: '[1, 2, 3]', 367 mykey3: 'ssssssssssssssssssssssssss', 368 mykey4: [false, true, false], 369 mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'], 370 mykey6: true, 371 } 372 } as Want 373 ], 374 // 指定的操作 375 actionType: wantAgent.OperationType.START_ABILITY, 376 requestCode: 0, 377 // wantagent对象类型 378 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 379}; 380 381class MyAbility extends UIAbility { 382 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 383 try { 384 // 创建wantAgent对象 385 wantAgent.getWantAgent(wantAgentInfo, (err: BusinessError, data: WantAgent) => { 386 if (err) { 387 console.info(`getWantAgent failed, code: ${err.code}, message: ${err.message}`); 388 } else { 389 wantAgentData = data; 390 } 391 392 try { 393 // 主动触发WantAgent实例 394 wantAgent.triggerAsync(wantAgentData, triggerInfo, this.context).then((data) => { 395 console.info(`trigger success, data: ${JSON.stringify(data)}`); 396 }).catch((err: BusinessError) => { 397 console.error(`triggerAsync failed! ${err.code} ${err.message}`); 398 }); 399 } catch (err) { 400 console.error(`triggerAsync failed! ${err.code} ${err.message}`); 401 } 402 }); 403 } catch (err) { 404 let code = (err as BusinessError).code; 405 let msg = (err as BusinessError).message; 406 console.error(`getWantAgent failed, code: ${code}, message: ${msg}.`); 407 } 408 } 409} 410``` 411 412## wantAgent.createLocalWantAgent<sup>20+</sup> 413 414createLocalWantAgent(info: LocalWantAgentInfo): WantAgent 415 416创建本地WantAgent实例。 417 418> **说明：** 419> 420> - 本接口创建的本地WantAgent实例仅存储于WantAgent客户端，不受WantAgent服务端管理。使用该本地实例时，需要校验实例，以保证安全性。 421> 422> - 本地WantAgent实例创建后，触发方法参见[wantAgent.triggerAsync](#wantagenttriggerasync20)接口说明。 423 424**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 425 426**系统接口**：此接口为系统接口。 427 428**模型约束**：此接口仅可在Stage模型下使用。 429 430**参数：** 431 432| 参数名 | 类型 | 必填 | 说明 | 433| ----------- | ----------------------------- | ---- | ------------------------------- | 434| info | [LocalWantAgentInfo](js-apis-inner-wantAgent-wantAgentInfo.md) | 是 | LocalWantAgent信息。 | 435 436**返回值：** 437 438| 类型 | 说明 | 439| ----------------------------------------------------------- | ------------------------------------------------------------ | 440| [WantAgent](js-apis-app-ability-wantAgent.md#wantagent) | 返回创建的WantAgent实例。 | 441 442**错误码：** 443 444以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 445 446| 错误码ID | 错误信息 | 447|-----------|--------------------| 448| 202 | Not System App. Interface caller is not a system app. | 449 450**示例：** 451 452```ts 453import { wantAgent, Want } from '@kit.AbilityKit'; 454import type { WantAgent } from '@kit.AbilityKit'; 455 456// 声明wantAgent实例 457let wantAgentData: WantAgent; 458// 创建LocalWantAgentInfo实例 459let localWantAgentInfo: wantAgent.LocalWantAgentInfo = { 460 wants: [ 461 { 462 deviceId: 'deviceId', 463 bundleName: 'com.example.myapplication', 464 abilityName: 'EntryAbility', 465 action: 'action1', 466 entities: ['entity1'], 467 type: 'MIMETYPE', 468 uri: 'key={true,true,false}', 469 parameters: 470 { 471 mykey0: 2222, 472 mykey1: [1, 2, 3], 473 mykey2: '[1, 2, 3]', 474 mykey3: 'ssssssssssssssssssssssssss', 475 mykey4: [false, true, false], 476 mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'], 477 mykey6: true, 478 } 479 } as Want 480 ], 481 operationType: wantAgent.OperationType.START_ABILITY, 482 requestCode: 0 483}; 484// 创建本地WantAgent实例 485try { 486 wantAgentData = wantAgent.createLocalWantAgent(localWantAgentInfo); 487} catch (err) { 488 console.error('createLocalWantAgent failed'); 489} 490``` 491 492## wantAgent.isLocalWantAgent<sup>20+</sup> 493 494isLocalWantAgent(agent: WantAgent): boolean 495 496判断WantAgent实例是否为本地实例。 497 498**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 499 500**系统接口**：此接口为系统接口。 501 502**模型约束**：此接口仅可在Stage模型下使用。 503 504**参数：** 505 506| 参数名 | 类型 | 必填 | 说明 | 507| ----------- | ----------------------------- | ---- | ------------------------------- | 508| agent | [WantAgent](js-apis-app-ability-wantAgent.md#wantagent) | 是 | WantAgent实例。 | 509 510**返回值：** 511 512| 类型 | 说明 | 513| ----------------------------------------------------------- | ------------------------------------------------------------ | 514| boolean | 返回WantAgent实例是否为本地实例的结果。返回true表示该WantAgent为保存在本地客户端的实例，返回false表示该WantAgent为保存在服务端的实例。 | 515 516**错误码：** 517 518以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 519 520| 错误码ID | 错误信息 | 521|-----------|--------------------| 522| 202 | Not System App. Interface caller is not a system app. | 523 524**示例：** 525 526```ts 527import { wantAgent } from '@kit.AbilityKit'; 528import type { WantAgent } from '@kit.AbilityKit'; 529 530// 声明wantAgent实例 531let wantAgentData: WantAgent; 532// 创建LocalWantAgentInfo实例 533let localWantAgentInfo: wantAgent.LocalWantAgentInfo = { 534 wants: [ 535 { 536 deviceId: 'deviceId', 537 bundleName: 'com.example.myapplication', 538 abilityName: 'EntryAbility', 539 action: 'action1', 540 entities: ['entity1'], 541 type: 'MIMETYPE', 542 uri: 'key={true,true,false}', 543 parameters: 544 { 545 mykey0: 2222, 546 mykey1: [1, 2, 3], 547 mykey2: '[1, 2, 3]', 548 mykey3: 'ssssssssssssssssssssssssss', 549 mykey4: [false, true, false], 550 mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'], 551 mykey6: true, 552 } 553 } as Want 554 ], 555 operationType: wantAgent.OperationType.START_ABILITY, 556 requestCode: 0 557}; 558 559// 创建WantAgent实例并获取是否为本地WantAgent实例 560try { 561 wantAgentData = wantAgent.createLocalWantAgent(localWantAgentInfo); 562 let isLocal: boolean = wantAgent.isLocalWantAgent(wantAgentData); 563} catch (err) { 564 console.error('call isLocalWantAgent failed'); 565} 566``` 567 568## OperationType 569 570表示操作WantAgent类型的枚举。 571 572**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 573 574| 名称 | 值 | 说明 | 575|-------------------------|---|-----------------------------------------------| 576| START_SERVICE_EXTENSION<sup>12+</sup> | 6 | 开启一个ServiceExtension。<br/>**系统接口**：该接口为系统接口。 |