1# UIAbilityContext (系统接口) 2 3<!--Kit: Ability Kit--> 4<!--Subsystem: Ability--> 5<!--Owner: @duan-sizhao--> 6<!--Designer: @ccllee1--> 7<!--Tester: @lixueqing513--> 8<!--Adviser: @huipeizi--> 9 10UIAbilityContext是需要保存状态的[UIAbility](js-apis-app-ability-uiAbility.md)所对应的context，继承自[Context](js-apis-inner-application-context.md)，提供UIAbility的相关配置信息以及操作UIAbility和ServiceExtensionAbility的方法，如启动UIAbility，停止当前UIAbilityContext所属的UIAbility，启动、停止、连接、断开连接ServiceExtensionAbility等。 11 12> **说明：** 13> 14> - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15> - 本模块接口仅可在Stage模型下使用。 16> - 本模块接口为系统接口。 17 18## 导入模块 19 20```ts 21import { common } from '@kit.AbilityKit'; 22``` 23 24> **关于示例代码的说明：** 25> 26> 在本文档的示例中，通过`this.context`来获取`UIAbilityContext`，其中`this`代表继承自`UIAbility`的`UIAbility`实例。如需要在页面中使用`UIAbilityContext`提供的能力，请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 27 28## UIAbilityContext 29 30### startAbilityForResultWithAccount 31 32startAbilityForResultWithAccount(want: Want, accountId: number, callback: AsyncCallback\<AbilityResult>): void 33 34启动一个Ability并在该Ability销毁时返回执行结果。使用callback异步回调。仅支持在主线程调用。 35 36> **说明：** 37> 38> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 39> 当accountId为当前用户时，无需进行权限校验。 40 41**需要权限**：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 42 43**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 44 45**系统接口**：此接口为系统接口。 46 47**参数：** 48 49| 参数名 | 类型 | 必填 | 说明 | 50| -------- | -------- | -------- | -------- | 51| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 52| accountId | number | 是 | 系统账号的账号ID，详情参考[getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getosaccountcount9)。 | 53| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | 是 | 启动Ability的回调函数，返回Ability结果。 | 54 55**错误码：** 56 57以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 58 59| 错误码ID | 错误信息 | 60| ------- | -------------------------------- | 61| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 62| 16000001 | The specified ability does not exist. | 63| 16000002 | Incorrect ability type. | 64| 16000004 | Cannot start an invisible component. | 65| 16000005 | The specified process does not have the permission. | 66| 16000006 | Cross-user operations are not allowed. | 67| 16000008 | The crowdtesting application expires. | 68| 16000009 | An ability cannot be started or stopped in Wukong mode. | 69| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 70| 16000011 | The context does not exist. | 71| 16000012 | The application is controlled. | 72| 16000013 | The application is controlled by EDM. | 73| 16000019 | No matching ability is found. | 74| 16000050 | Internal error. | 75| 16000053 | The ability is not on the top of the UI. | 76| 16000055 | Installation-free timed out. | 77| 16000071 | App clone is not supported. | 78| 16000072 | App clone or multi-instance is not supported. | 79| 16000073 | The app clone index is invalid. | 80| 16000076 | The app instance key is invalid. | 81| 16000077 | The number of app instances reaches the limit. | 82| 16000078 | The multi-instance is not supported. | 83| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 84| 16000080 | Creating a new instance is not supported. | 85| 16200001 | The caller has been released. | 86 87**示例：** 88 89```ts 90import { UIAbility, common, Want } from '@kit.AbilityKit'; 91import { BusinessError } from '@kit.BasicServicesKit'; 92 93export default class EntryAbility extends UIAbility { 94 onForeground() { 95 let want: Want = { 96 deviceId: '', 97 bundleName: 'com.example.myapplication', 98 abilityName: 'EntryAbility' 99 }; 100 let accountId = 100; 101 102 try { 103 this.context.startAbilityForResultWithAccount(want, accountId, (err: BusinessError, result: common.AbilityResult) => { 104 if (err.code) { 105 // 处理业务逻辑错误 106 console.error(`startAbilityForResultWithAccount failed, code is ${err.code}, message is ${err.message}`); 107 return; 108 } 109 // 执行正常业务 110 console.info('startAbilityForResultWithAccount succeed'); 111 }); 112 } catch (err) { 113 // 处理入参错误异常 114 let code = (err as BusinessError).code; 115 let message = (err as BusinessError).message; 116 console.error(`startAbilityForResultWithAccount failed, code is ${code}, message is ${message}`); 117 } 118 } 119} 120``` 121 122 123### startAbilityForResultWithAccount 124 125startAbilityForResultWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback\<void\>): void 126 127启动一个Ability并在该Ability销毁时返回执行结果。使用callback异步回调。仅支持在主线程调用。 128 129> **说明：** 130> 131> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 132> 当accountId为当前用户时，无需进行权限校验。 133 134**需要权限**：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 135 136**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 137 138**系统接口**：此接口为系统接口。 139 140**参数：** 141 142| 参数名 | 类型 | 必填 | 说明 | 143| -------- | -------- | -------- | -------- | 144| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 145| accountId | number | 是 | 系统账号的账号ID，详情参考[getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getosaccountcount9)。 | 146| options | [StartOptions](js-apis-app-ability-startOptions.md) | 是 | 启动Ability所携带的参数。 | 147| callback | AsyncCallback\<void\> | 是 | 启动Ability后，Ability被销毁时的回调函数。 | 148 149**错误码：** 150 151以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 152 153| 错误码ID | 错误信息 | 154| ------- | -------------------------------- | 155| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 156| 16000001 | The specified ability does not exist. | 157| 16000004 | Cannot start an invisible component. | 158| 16000005 | The specified process does not have the permission. | 159| 16000006 | Cross-user operations are not allowed. | 160| 16000008 | The crowdtesting application expires. | 161| 16000009 | An ability cannot be started or stopped in Wukong mode. | 162| 16000011 | The context does not exist. | 163| 16000012 | The application is controlled. | 164| 16000013 | The application is controlled by EDM. | 165| 16000019 | No matching ability is found. | 166| 16000050 | Internal error. | 167| 16000053 | The ability is not on the top of the UI. | 168| 16000055 | Installation-free timed out. | 169| 16000071 | App clone is not supported. | 170| 16000072 | App clone or multi-instance is not supported. | 171| 16000073 | The app clone index is invalid. | 172| 16000076 | The app instance key is invalid. | 173| 16000077 | The number of app instances reaches the limit. | 174| 16000078 | The multi-instance is not supported. | 175| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 176| 16000080 | Creating a new instance is not supported. | 177| 16200001 | The caller has been released. | 178 179**示例：** 180 181```ts 182import { UIAbility, StartOptions, Want } from '@kit.AbilityKit'; 183import { BusinessError } from '@kit.BasicServicesKit'; 184 185export default class EntryAbility extends UIAbility { 186 onForeground() { 187 let want: Want = { 188 deviceId: '', 189 bundleName: 'com.example.myapplication', 190 abilityName: 'EntryAbility' 191 }; 192 let accountId = 100; 193 let options: StartOptions = { 194 displayId: 0 195 }; 196 197 try { 198 this.context.startAbilityForResultWithAccount(want, accountId, options, (err: BusinessError) => { 199 if (err.code) { 200 // 处理业务逻辑错误 201 console.error(`startAbilityForResultWithAccount failed, code is ${err.code}, message is ${err.message}`); 202 return; 203 } 204 // 执行正常业务 205 console.info('startAbilityForResultWithAccount succeed'); 206 }); 207 } catch (err) { 208 // 处理入参错误异常 209 let code = (err as BusinessError).code; 210 let message = (err as BusinessError).message; 211 console.error(`startAbilityForResultWithAccount failed, code is ${code}, message is ${message}`); 212 } 213 } 214} 215``` 216 217 218### startAbilityForResultWithAccount 219 220startAbilityForResultWithAccount(want: Want, accountId: number, options?: StartOptions): Promise\<AbilityResult\> 221 222启动一个Ability并在该Ability销毁时返回执行结果。使用Promise异步回调。仅支持在主线程调用。 223 224> **说明：** 225> 226> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 227> 当accountId为当前用户时，无需进行权限校验。 228 229**需要权限**：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 230 231**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 232 233**系统接口**：此接口为系统接口。 234 235**参数：** 236 237| 参数名 | 类型 | 必填 | 说明 | 238| -------- | -------- | -------- | -------- | 239| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 240| accountId | number | 是 | 系统账号的账号ID，详情参考[getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getosaccountcount9)。 | 241| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否 | 启动Ability所携带的参数。 | 242 243**返回值：** 244 245| 类型 | 说明 | 246| -------- | -------- | 247| Promise<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Ability被销毁时的回调函数，包含AbilityResult参数。 | 248 249**错误码：** 250 251以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 252 253| 错误码ID | 错误信息 | 254| ------- | -------------------------------- | 255| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 256| 16000001 | The specified ability does not exist. | 257| 16000002 | Incorrect ability type. | 258| 16000004 | Cannot start an invisible component. | 259| 16000005 | The specified process does not have the permission. | 260| 16000006 | Cross-user operations are not allowed. | 261| 16000008 | The crowdtesting application expires. | 262| 16000009 | An ability cannot be started or stopped in Wukong mode. | 263| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 264| 16000011 | The context does not exist. | 265| 16000012 | The application is controlled. | 266| 16000013 | The application is controlled by EDM. | 267| 16000019 | No matching ability is found. | 268| 16000050 | Internal error. | 269| 16000053 | The ability is not on the top of the UI. | 270| 16000055 | Installation-free timed out. | 271| 16000071 | App clone is not supported. | 272| 16000072 | App clone or multi-instance is not supported. | 273| 16000073 | The app clone index is invalid. | 274| 16000076 | The app instance key is invalid. | 275| 16000077 | The number of app instances reaches the limit. | 276| 16000078 | The multi-instance is not supported. | 277| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 278| 16000080 | Creating a new instance is not supported. | 279| 16200001 | The caller has been released. | 280 281**示例：** 282 283```ts 284import { UIAbility, StartOptions, Want, common } from '@kit.AbilityKit'; 285import { BusinessError } from '@kit.BasicServicesKit'; 286 287export default class EntryAbility extends UIAbility { 288 onForeground() { 289 let want: Want = { 290 deviceId: '', 291 bundleName: 'com.example.myapplication', 292 abilityName: 'EntryAbility' 293 }; 294 let accountId = 100; 295 let options: StartOptions = { 296 displayId: 0 297 }; 298 299 try { 300 this.context.startAbilityForResultWithAccount(want, accountId, options) 301 .then((result: common.AbilityResult) => { 302 // 执行正常业务 303 console.info('startAbilityForResultWithAccount succeed'); 304 }) 305 .catch((err: BusinessError) => { 306 // 处理业务逻辑错误 307 console.error(`startAbilityForResultWithAccount failed, code is ${err.code}, message is ${err.message}`); 308 }); 309 } catch (err) { 310 // 处理入参错误异常 311 let code = (err as BusinessError).code; 312 let message = (err as BusinessError).message; 313 console.error(`startAbilityForResultWithAccount failed, code is ${code}, message is ${message}`); 314 } 315 } 316} 317``` 318### startServiceExtensionAbility 319 320startServiceExtensionAbility(want: Want, callback: AsyncCallback\<void>): void 321 322启动一个新的ServiceExtensionAbility。使用callback异步回调。 323 324**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 325 326**系统接口**：此接口为系统接口。 327 328**参数：** 329 330| 参数名 | 类型 | 必填 | 说明 | 331| -------- | -------- | -------- | -------- | 332| want | [Want](js-apis-app-ability-want.md) | 是 | 启动ServiceExtensionAbility的want信息。 | 333| callback | AsyncCallback\<void\> | 是 | 启动ServiceExtensionAbility的回调函数。 | 334 335**错误码：** 336 337以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 338 339| 错误码ID | 错误信息 | 340| ------- | -------------------------------- | 341| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 342| 16000001 | The specified ability does not exist. | 343| 16000002 | Incorrect ability type. | 344| 16000004 | Cannot start an invisible component. | 345| 16000005 | The specified process does not have the permission. | 346| 16000006 | Cross-user operations are not allowed. | 347| 16000008 | The crowdtesting application expires. | 348| 16000011 | The context does not exist. | 349| 16000012 | The application is controlled. | 350| 16000013 | The application is controlled by EDM. | 351| 16000019 | No matching ability is found. | 352| 16000050 | Internal error. | 353| 16200001 | The caller has been released. | 354 355**示例：** 356 357```ts 358import { UIAbility, Want } from '@kit.AbilityKit'; 359import { BusinessError } from '@kit.BasicServicesKit'; 360 361export default class EntryAbility extends UIAbility { 362 onForeground() { 363 let want: Want = { 364 deviceId: '', 365 bundleName: 'com.example.myapplication', 366 abilityName: 'ServiceExtensionAbility' 367 }; 368 369 try { 370 this.context.startServiceExtensionAbility(want, (error: BusinessError) => { 371 if (error.code) { 372 // 处理业务逻辑错误 373 console.error(`startServiceExtensionAbility failed, code is ${error.code}, message is ${error.message}`); 374 return; 375 } 376 // 执行正常业务 377 console.info('startServiceExtensionAbility succeed'); 378 }); 379 } catch (err) { 380 // 处理入参错误异常 381 let code = (err as BusinessError).code; 382 let message = (err as BusinessError).message; 383 console.error(`startServiceExtensionAbility failed, code is ${code}, message is ${message}`); 384 } 385 } 386} 387``` 388 389### startServiceExtensionAbility 390 391startServiceExtensionAbility(want: Want): Promise\<void> 392 393启动一个新的ServiceExtensionAbility。使用Promise异步回调。 394 395**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 396 397**系统接口**：此接口为系统接口。 398 399**参数：** 400 401| 参数名 | 类型 | 必填 | 说明 | 402| -------- | -------- | -------- | -------- | 403| want | [Want](js-apis-app-ability-want.md) | 是 | 启动ServiceExtensionAbility的want信息。 | 404 405**返回值：** 406 407| 类型 | 说明 | 408| -------- | -------- | 409| Promise\<void> | Promise对象，无返回结果。 | 410 411**错误码：** 412 413以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 414 415| 错误码ID | 错误信息 | 416| ------- | -------------------------------- | 417| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 418| 16000001 | The specified ability does not exist. | 419| 16000002 | Incorrect ability type. | 420| 16000004 | Cannot start an invisible component. | 421| 16000005 | The specified process does not have the permission. | 422| 16000006 | Cross-user operations are not allowed. | 423| 16000008 | The crowdtesting application expires. | 424| 16000011 | The context does not exist. | 425| 16000012 | The application is controlled. | 426| 16000013 | The application is controlled by EDM. | 427| 16000019 | No matching ability is found. | 428| 16000050 | Internal error. | 429| 16200001 | The caller has been released. | 430 431**示例：** 432 433```ts 434import { UIAbility, Want } from '@kit.AbilityKit'; 435import { BusinessError } from '@kit.BasicServicesKit'; 436 437export default class EntryAbility extends UIAbility { 438 onForeground() { 439 let want: Want = { 440 deviceId: '', 441 bundleName: 'com.example.myapplication', 442 abilityName: 'ServiceExtensionAbility' 443 }; 444 445 try { 446 this.context.startServiceExtensionAbility(want) 447 .then(() => { 448 // 执行正常业务 449 console.info('startServiceExtensionAbility succeed'); 450 }) 451 .catch((err: BusinessError) => { 452 // 处理业务逻辑错误 453 console.error(`startServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`); 454 }); 455 } catch (err) { 456 // 处理入参错误异常 457 let code = (err as BusinessError).code; 458 let message = (err as BusinessError).message; 459 console.error(`startServiceExtensionAbility failed, code is ${code}, message is ${message}`); 460 } 461 } 462} 463``` 464 465### startServiceExtensionAbilityWithAccount 466 467startServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\<void>): void 468 469启动一个新的ServiceExtensionAbility。使用callback异步回调。 470 471> **说明：** 472> 473> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 474> 当accountId为当前用户时，无需进行权限校验。 475 476**需要权限**：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 477 478**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 479 480**系统接口**：此接口为系统接口。 481 482**参数：** 483 484| 参数名 | 类型 | 必填 | 说明 | 485| -------- | -------- | -------- | -------- | 486| want | [Want](js-apis-app-ability-want.md) | 是 | 启动ServiceExtensionAbility的want信息。 | 487| accountId | number | 是 | 系统账号的账号ID，详情参考[getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getosaccountcount9)。 | 488| callback | AsyncCallback\<void\> | 是 | 启动ServiceExtensionAbility的回调函数。 | 489 490**错误码：** 491 492以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 493 494| 错误码ID | 错误信息 | 495| ------- | -------------------------------- | 496| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 497| 16000001 | The specified ability does not exist. | 498| 16000002 | Incorrect ability type. | 499| 16000004 | Cannot start an invisible component. | 500| 16000005 | The specified process does not have the permission. | 501| 16000006 | Cross-user operations are not allowed. | 502| 16000008 | The crowdtesting application expires. | 503| 16000011 | The context does not exist. | 504| 16000012 | The application is controlled. | 505| 16000013 | The application is controlled by EDM. | 506| 16000019 | No matching ability is found. | 507| 16000050 | Internal error. | 508| 16200001 | The caller has been released. | 509 510**示例：** 511 512```ts 513import { UIAbility, Want } from '@kit.AbilityKit'; 514import { BusinessError } from '@kit.BasicServicesKit'; 515 516export default class EntryAbility extends UIAbility { 517 onForeground() { 518 let want: Want = { 519 deviceId: '', 520 bundleName: 'com.example.myapplication', 521 abilityName: 'ServiceExtensionAbility' 522 }; 523 let accountId = 100; 524 525 try { 526 this.context.startServiceExtensionAbilityWithAccount(want, accountId, (err: BusinessError) => { 527 if (err.code) { 528 // 处理业务逻辑错误 529 console.error(`startServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`); 530 return; 531 } 532 // 执行正常业务 533 console.info('startServiceExtensionAbilityWithAccount succeed'); 534 }); 535 } catch (err) { 536 // 处理入参错误异常 537 let code = (err as BusinessError).code; 538 let message = (err as BusinessError).message; 539 console.error(`startServiceExtensionAbilityWithAccount failed, code is ${code}, message is ${message}`); 540 } 541 } 542} 543``` 544 545### startServiceExtensionAbilityWithAccount 546 547startServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise\<void> 548 549启动一个新的ServiceExtensionAbility。使用Promise异步回调。 550 551> **说明：** 552> 553> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 554> 当accountId为当前用户时，无需进行权限校验。 555 556**需要权限**：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 557 558**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 559 560**系统接口**：此接口为系统接口。 561 562**参数：** 563 564| 参数名 | 类型 | 必填 | 说明 | 565| -------- | -------- | -------- | -------- | 566| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 567| accountId | number | 是 | 系统账号的账号ID，详情参考[getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getosaccountcount9)。 | 568 569**返回值：** 570 571| 类型 | 说明 | 572| -------- | -------- | 573| Promise\<void> | Promise对象，无返回结果。 | 574 575**错误码：** 576 577以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 578 579| 错误码ID | 错误信息 | 580| ------- | -------------------------------- | 581| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 582| 16000001 | The specified ability does not exist. | 583| 16000002 | Incorrect ability type. | 584| 16000004 | Cannot start an invisible component. | 585| 16000005 | The specified process does not have the permission. | 586| 16000006 | Cross-user operations are not allowed. | 587| 16000008 | The crowdtesting application expires. | 588| 16000011 | The context does not exist. | 589| 16000012 | The application is controlled. | 590| 16000013 | The application is controlled by EDM. | 591| 16000019 | No matching ability is found. | 592| 16000050 | Internal error. | 593| 16200001 | The caller has been released. | 594 595**示例：** 596 597```ts 598import { UIAbility, Want } from '@kit.AbilityKit'; 599import { BusinessError } from '@kit.BasicServicesKit'; 600 601export default class EntryAbility extends UIAbility { 602 onForeground() { 603 let want: Want = { 604 deviceId: '', 605 bundleName: 'com.example.myapplication', 606 abilityName: 'ServiceExtensionAbility' 607 }; 608 let accountId = 100; 609 610 try { 611 this.context.startServiceExtensionAbilityWithAccount(want, accountId) 612 .then(() => { 613 // 执行正常业务 614 console.info('startServiceExtensionAbilityWithAccount succeed'); 615 }) 616 .catch((err: BusinessError) => { 617 // 处理业务逻辑错误 618 console.error(`startServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`); 619 }); 620 } catch (err) { 621 // 处理入参错误异常 622 let code = (err as BusinessError).code; 623 let message = (err as BusinessError).message; 624 console.error(`startServiceExtensionAbilityWithAccount failed, code is ${code}, message is ${message}`); 625 } 626 } 627} 628``` 629### stopServiceExtensionAbility 630 631stopServiceExtensionAbility(want: Want, callback: AsyncCallback\<void>): void 632 633停止同一应用程序内的服务。使用callback异步回调。 634 635**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 636 637**系统接口**：此接口为系统接口。 638 639**参数：** 640 641| 参数名 | 类型 | 必填 | 说明 | 642| -------- | -------- | -------- | -------- | 643| want | [Want](js-apis-app-ability-want.md) | 是 | 停止ServiceExtensionAbility的want信息。 | 644| callback | AsyncCallback\<void\> | 是 | 停止ServiceExtensionAbility的回调函数。 | 645 646**错误码：** 647 648以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 649 650| 错误码ID | 错误信息 | 651| ------- | -------------------------------- | 652| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 653| 16000001 | The specified ability does not exist. | 654| 16000002 | Incorrect ability type. | 655| 16000004 | Cannot start an invisible component. | 656| 16000005 | The specified process does not have the permission. | 657| 16000006 | Cross-user operations are not allowed. | 658| 16000011 | The context does not exist. | 659| 16000012 | The application is controlled. | 660| 16000013 | The application is controlled by EDM. | 661| 16000050 | Internal error. | 662| 16200001 | The caller has been released. | 663 664**示例：** 665 666```ts 667import { UIAbility, Want } from '@kit.AbilityKit'; 668import { BusinessError } from '@kit.BasicServicesKit'; 669 670export default class EntryAbility extends UIAbility { 671 onForeground() { 672 let want: Want = { 673 deviceId: '', 674 bundleName: 'com.example.myapplication', 675 abilityName: 'ServiceExtensionAbility' 676 }; 677 678 try { 679 this.context.stopServiceExtensionAbility(want, (err: BusinessError) => { 680 if (err.code) { 681 // 处理业务逻辑错误 682 console.error(`stopServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`); 683 return; 684 } 685 // 执行正常业务 686 console.info('stopServiceExtensionAbility succeed'); 687 }); 688 } catch (err) { 689 // 处理入参错误异常 690 let code = (err as BusinessError).code; 691 let message = (err as BusinessError).message; 692 console.error(`stopServiceExtensionAbility failed, code is ${code}, message is ${message}`); 693 } 694 } 695} 696``` 697 698### stopServiceExtensionAbility 699 700stopServiceExtensionAbility(want: Want): Promise\<void> 701 702停止同一应用程序内的服务。使用Promise异步回调。 703 704**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 705 706**系统接口**：此接口为系统接口。 707 708**参数：** 709 710| 参数名 | 类型 | 必填 | 说明 | 711| -------- | -------- | -------- | -------- | 712| want | [Want](js-apis-app-ability-want.md) | 是 | 停止ServiceExtensionAbility的want信息。 | 713 714**返回值：** 715 716| 类型 | 说明 | 717| -------- | -------- | 718| Promise\<void> | Promise对象，无返回结果。 | 719 720**错误码：** 721 722以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 723 724| 错误码ID | 错误信息 | 725| ------- | -------------------------------- | 726| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 727| 16000001 | The specified ability does not exist. | 728| 16000002 | Incorrect ability type. | 729| 16000004 | Cannot start an invisible component. | 730| 16000005 | The specified process does not have the permission. | 731| 16000006 | Cross-user operations are not allowed. | 732| 16000011 | The context does not exist. | 733| 16000050 | Internal error. | 734| 16200001 | The caller has been released. | 735 736**示例：** 737 738```ts 739import { UIAbility, Want } from '@kit.AbilityKit'; 740import { BusinessError } from '@kit.BasicServicesKit'; 741 742export default class EntryAbility extends UIAbility { 743 onForeground() { 744 let want: Want = { 745 deviceId: '', 746 bundleName: 'com.example.myapplication', 747 abilityName: 'ServiceExtensionAbility' 748 }; 749 750 try { 751 this.context.stopServiceExtensionAbility(want) 752 .then(() => { 753 // 执行正常业务 754 console.info('stopServiceExtensionAbility succeed'); 755 }) 756 .catch((err: BusinessError) => { 757 // 处理业务逻辑错误 758 console.error(`stopServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`); 759 }); 760 } catch (err) { 761 // 处理入参错误异常 762 let code = (err as BusinessError).code; 763 let message = (err as BusinessError).message; 764 console.error(`stopServiceExtensionAbility failed, code is ${code}, message is ${message}`); 765 } 766 } 767} 768``` 769 770### stopServiceExtensionAbilityWithAccount 771 772stopServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\<void>): void 773 774停止同一应用程序内指定账户的服务。使用callback异步回调。 775 776> **说明：** 777> 778> 当accountId为当前用户时，无需进行权限校验。 779 780**需要权限**：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 781 782**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 783 784**系统接口**：此接口为系统接口。 785 786**参数：** 787 788| 参数名 | 类型 | 必填 | 说明 | 789| -------- | -------- | -------- | -------- | 790| want | [Want](js-apis-app-ability-want.md) | 是 | 停止ServiceExtensionAbility的want信息。 | 791| accountId | number | 是 | 系统账号的账号ID，详情参考[getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getosaccountcount9)。 | 792| callback | AsyncCallback\<void\> | 是 | 停止ServiceExtensionAbility的回调函数。 | 793 794**错误码：** 795 796以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 797 798| 错误码ID | 错误信息 | 799| ------- | -------------------------------- | 800| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 801| 16000001 | The specified ability does not exist. | 802| 16000002 | Incorrect ability type. | 803| 16000004 | Cannot start an invisible component. | 804| 16000005 | The specified process does not have the permission. | 805| 16000006 | Cross-user operations are not allowed. | 806| 16000011 | The context does not exist. | 807| 16000050 | Internal error. | 808| 16200001 | The caller has been released. | 809 810**示例：** 811 812```ts 813import { UIAbility, Want } from '@kit.AbilityKit'; 814import { BusinessError } from '@kit.BasicServicesKit'; 815 816export default class EntryAbility extends UIAbility { 817 onForeground() { 818 let want: Want = { 819 deviceId: '', 820 bundleName: 'com.example.myapplication', 821 abilityName: 'ServiceExtensionAbility' 822 }; 823 let accountId = 100; 824 825 try { 826 this.context.stopServiceExtensionAbilityWithAccount(want, accountId, (err: BusinessError) => { 827 if (err.code) { 828 // 处理业务逻辑错误 829 console.error(`stopServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`); 830 return; 831 } 832 // 执行正常业务 833 console.info('stopServiceExtensionAbilityWithAccount succeed'); 834 }); 835 } catch (err) { 836 // 处理入参错误异常 837 let code = (err as BusinessError).code; 838 let message = (err as BusinessError).message; 839 console.error(`stopServiceExtensionAbilityWithAccount failed, code is ${code}, message is ${message}`); 840 } 841 } 842} 843``` 844 845### stopServiceExtensionAbilityWithAccount 846 847stopServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise\<void> 848 849停止同一应用程序内指定账户的服务。使用Promise异步回调。 850 851> **说明：** 852> 853> 当accountId为当前用户时，无需进行权限校验。 854 855**需要权限**：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 856 857**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 858 859**系统接口**：此接口为系统接口。 860 861**参数：** 862 863| 参数名 | 类型 | 必填 | 说明 | 864| -------- | -------- | -------- | -------- | 865| want | [Want](js-apis-app-ability-want.md) | 是 | 停止ServiceExtensionAbility的want信息。 | 866| accountId | number | 是 | 系统账号的账号ID，详情参考[getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getosaccountcount9)。 | 867 868**返回值：** 869 870| 类型 | 说明 | 871| -------- | -------- | 872| Promise\<void> | Promise对象，无返回结果。 | 873 874**错误码：** 875 876以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 877 878| 错误码ID | 错误信息 | 879| ------- | -------------------------------- | 880| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 881| 16000001 | The specified ability does not exist. | 882| 16000002 | Incorrect ability type. | 883| 16000004 | Cannot start an invisible component. | 884| 16000005 | The specified process does not have the permission. | 885| 16000006 | Cross-user operations are not allowed. | 886| 16000011 | The context does not exist. | 887| 16000050 | Internal error. | 888| 16200001 | The caller has been released. | 889 890**示例：** 891 892```ts 893import { UIAbility, Want } from '@kit.AbilityKit'; 894import { BusinessError } from '@kit.BasicServicesKit'; 895 896export default class EntryAbility extends UIAbility { 897 onForeground() { 898 let want: Want = { 899 deviceId: '', 900 bundleName: 'com.example.myapplication', 901 abilityName: 'ServiceExtensionAbility' 902 }; 903 let accountId = 100; 904 905 try { 906 this.context.stopServiceExtensionAbilityWithAccount(want, accountId) 907 .then(() => { 908 // 执行正常业务 909 console.info('stopServiceExtensionAbilityWithAccount succeed'); 910 }) 911 .catch((err: BusinessError) => { 912 // 处理业务逻辑错误 913 console.error(`stopServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`); 914 }); 915 } catch (err) { 916 // 处理入参错误异常 917 let code = (err as BusinessError).code; 918 let message = (err as BusinessError).message; 919 console.error(`stopServiceExtensionAbilityWithAccount failed, code is ${code}, message is ${message}`); 920 } 921 } 922} 923``` 924 925### connectServiceExtensionAbilityWithAccount 926 927connectServiceExtensionAbilityWithAccount(want: Want, accountId: number, options: ConnectOptions): number 928 929将当前Ability连接到一个指定account的ServiceExtensionAbility。仅支持在主线程调用。 930 931当前仅在Phone、Tablet设备上生效。 932 933> **说明：** 934> 935> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 936> 当accountId为当前用户时，无需进行权限校验。 937 938**需要权限**：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 939 940**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 941 942**系统接口**：此接口为系统接口。 943 944**参数：** 945 946| 参数名 | 类型 | 必填 | 说明 | 947| -------- | -------- | -------- | -------- | 948| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 949| accountId | number | 是 | 系统账号的账号ID，详情参考[getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getosaccountcount9)。 | 950| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | 是 | 与ServiceExtensionAbility建立连接后回调函数的实例。 | 951 952**返回值：** 953 954| 类型 | 说明 | 955| -------- | -------- | 956| number | 返回Ability连接的结果code。 | 957 958**错误码：** 959 960以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 961 962| 错误码ID | 错误信息 | 963| ------- | -------------------------------- | 964| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 965| 16000001 | The specified ability does not exist. | 966| 16000002 | Incorrect ability type. | 967| 16000004 | Cannot start an invisible component. | 968| 16000005 | The specified process does not have the permission. | 969| 16000006 | Cross-user operations are not allowed. | 970| 16000008 | The crowdtesting application expires. | 971| 16000053 | The ability is not on the top of the UI. | 972| 16000055 | Installation-free timed out. | 973| 16000011 | The context does not exist. | 974| 16000050 | Internal error. | 975 976**示例：** 977 978```ts 979import { UIAbility, Want, common } from '@kit.AbilityKit'; 980import { rpc } from '@kit.IPCKit'; 981import { BusinessError } from '@kit.BasicServicesKit'; 982 983export default class EntryAbility extends UIAbility { 984 onForeground() { 985 let want: Want = { 986 deviceId: '', 987 bundleName: 'com.example.myapplication', 988 abilityName: 'ServiceExtensionAbility' 989 }; 990 let accountId = 100; 991 let commRemote: rpc.IRemoteObject; 992 let options: common.ConnectOptions = { 993 onConnect(elementName, remote) { 994 commRemote = remote; 995 console.info('onConnect...'); 996 }, 997 onDisconnect(elementName) { 998 console.info('onDisconnect...'); 999 }, 1000 onFailed(code) { 1001 console.info('onFailed...'); 1002 } 1003 }; 1004 let connection: number; 1005 1006 try { 1007 connection = this.context.connectServiceExtensionAbilityWithAccount(want, accountId, options); 1008 } catch (err) { 1009 // 处理入参错误异常 1010 let code = (err as BusinessError).code; 1011 let message = (err as BusinessError).message; 1012 console.error(`connectServiceExtensionAbility failed, code is ${code}, message is ${message}`); 1013 } 1014 } 1015} 1016``` 1017 1018### startAbilityWithAccount 1019 1020startAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\<void\>): void 1021 1022根据want和accountId启动Ability。使用callback异步回调。仅支持在主线程调用。 1023 1024> **说明：** 1025> 1026> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 1027> 当accountId为当前用户时，无需进行权限校验。 1028 1029**需要权限**：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 1030 1031**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1032 1033**系统接口**：此接口为系统接口。 1034 1035**参数：** 1036 1037| 参数名 | 类型 | 必填 | 说明 | 1038| -------- | -------- | -------- | -------- | 1039| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 1040| accountId | number | 是 | 系统账号的账号ID，详情参考[getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getosaccountcount9)。 | 1041| callback | AsyncCallback\<void\> | 是 | 启动Ability的回调函数。 | 1042 1043**错误码：** 1044 1045以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1046 1047| 错误码ID | 错误信息 | 1048| ------- | -------------------------------- | 1049| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1050| 16000001 | The specified ability does not exist. | 1051| 16000002 | Incorrect ability type. | 1052| 16000004 | Cannot start an invisible component. | 1053| 16000005 | The specified process does not have the permission. | 1054| 16000006 | Cross-user operations are not allowed. | 1055| 16000008 | The crowdtesting application expires. | 1056| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1057| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 1058| 16000011 | The context does not exist. | 1059| 16000012 | The application is controlled. | 1060| 16000013 | The application is controlled by EDM. | 1061| 16000019 | No matching ability is found. | 1062| 16000050 | Internal error. | 1063| 16000053 | The ability is not on the top of the UI. | 1064| 16000055 | Installation-free timed out. | 1065| 16000071 | App clone is not supported. | 1066| 16000072 | App clone or multi-instance is not supported. | 1067| 16000073 | The app clone index is invalid. | 1068| 16000076 | The app instance key is invalid. | 1069| 16000077 | The number of app instances reaches the limit. | 1070| 16000078 | The multi-instance is not supported. | 1071| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 1072| 16000080 | Creating a new instance is not supported. | 1073| 16200001 | The caller has been released. | 1074 1075**示例：** 1076 1077```ts 1078import { UIAbility, Want } from '@kit.AbilityKit'; 1079import { BusinessError } from '@kit.BasicServicesKit'; 1080 1081export default class EntryAbility extends UIAbility { 1082 onForeground() { 1083 let want: Want = { 1084 deviceId: '', 1085 bundleName: 'com.example.myapplication', 1086 abilityName: 'EntryAbility' 1087 }; 1088 let accountId = 100; 1089 1090 try { 1091 this.context.startAbilityWithAccount(want, accountId, (err: BusinessError) => { 1092 if (err.code) { 1093 // 处理业务逻辑错误 1094 console.error(`startAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`); 1095 return; 1096 } 1097 // 执行正常业务 1098 console.info('startAbilityWithAccount succeed'); 1099 }); 1100 } catch (err) { 1101 // 处理入参错误异常 1102 let code = (err as BusinessError).code; 1103 let message = (err as BusinessError).message; 1104 console.error(`startAbilityWithAccount failed, code is ${code}, message is ${message}`); 1105 } 1106 } 1107} 1108``` 1109 1110 1111### startAbilityWithAccount 1112 1113startAbilityWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback\<void\>): void 1114 1115根据want、accountId及startOptions启动Ability。使用callback异步回调。仅支持在主线程调用。 1116 1117> **说明：** 1118> 1119> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 1120> 当accountId为当前用户时，无需进行权限校验。 1121 1122**需要权限**：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 1123 1124**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1125 1126**系统接口**：此接口为系统接口。 1127 1128**参数：** 1129 1130| 参数名 | 类型 | 必填 | 说明 | 1131| -------- | -------- | -------- | -------- | 1132| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 1133| accountId | number | 是 | 系统账号的账号ID，详情参考[getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getosaccountcount9)。| 1134| options | [StartOptions](js-apis-app-ability-startOptions.md) | 是 | 启动Ability所携带的参数。 | 1135| callback | AsyncCallback\<void\> | 是 | 启动Ability的回调函数。 | 1136 1137**错误码：** 1138 1139以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1140 1141| 错误码ID | 错误信息 | 1142| ------- | -------------------------------- | 1143| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1144| 16000001 | The specified ability does not exist. | 1145| 16000004 | Cannot start an invisible component. | 1146| 16000005 | The specified process does not have the permission. | 1147| 16000006 | Cross-user operations are not allowed. | 1148| 16000008 | The crowdtesting application expires. | 1149| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1150| 16000011 | The context does not exist. | 1151| 16000012 | The application is controlled. | 1152| 16000013 | The application is controlled by EDM. | 1153| 16000019 | No matching ability is found. | 1154| 16000050 | Internal error. | 1155| 16000053 | The ability is not on the top of the UI. | 1156| 16000055 | Installation-free timed out. | 1157| 16000071 | App clone is not supported. | 1158| 16000072 | App clone or multi-instance is not supported. | 1159| 16000073 | The app clone index is invalid. | 1160| 16000076 | The app instance key is invalid. | 1161| 16000077 | The number of app instances reaches the limit. | 1162| 16000078 | The multi-instance is not supported. | 1163| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 1164| 16000080 | Creating a new instance is not supported. | 1165| 16200001 | The caller has been released. | 1166 1167**示例：** 1168 1169```ts 1170import { UIAbility, Want, StartOptions } from '@kit.AbilityKit'; 1171import { BusinessError } from '@kit.BasicServicesKit'; 1172 1173export default class EntryAbility extends UIAbility { 1174 onForeground() { 1175 let want: Want = { 1176 deviceId: '', 1177 bundleName: 'com.example.myapplication', 1178 abilityName: 'EntryAbility' 1179 }; 1180 let accountId = 100; 1181 let options: StartOptions = { 1182 displayId: 0 1183 }; 1184 1185 try { 1186 this.context.startAbilityWithAccount(want, accountId, options, (err: BusinessError) => { 1187 if (err.code) { 1188 // 处理业务逻辑错误 1189 console.error(`startAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`); 1190 return; 1191 } 1192 // 执行正常业务 1193 console.info('startAbilityWithAccount succeed'); 1194 }); 1195 } catch (err) { 1196 // 处理入参错误异常 1197 let code = (err as BusinessError).code; 1198 let message = (err as BusinessError).message; 1199 console.error(`startAbilityWithAccount failed, code is ${code}, message is ${message}`); 1200 } 1201 } 1202} 1203``` 1204 1205 1206### startAbilityWithAccount 1207 1208startAbilityWithAccount(want: Want, accountId: number, options?: StartOptions): Promise\<void\> 1209 1210根据want、accountId和startOptions启动Ability。使用Promise异步回调。仅支持在主线程调用。 1211 1212> **说明：** 1213> 1214> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 1215> 当accountId为当前用户时，无需进行权限校验。 1216 1217**需要权限**：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 1218 1219**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1220 1221**系统接口**：此接口为系统接口。 1222 1223**参数：** 1224 1225| 参数名 | 类型 | 必填 | 说明 | 1226| -------- | -------- | -------- | -------- | 1227| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 1228| accountId | number | 是 | 系统账号的账号ID，详情参考[getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getosaccountcount9)。 | 1229| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否 | 启动Ability所携带的参数。 | 1230 1231**返回值：** 1232 1233| 类型 | 说明 | 1234| -------- | -------- | 1235| Promise\<void> | Promise对象，无返回结果。 | 1236 1237**错误码：** 1238 1239以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1240 1241| 错误码ID | 错误信息 | 1242| ------- | -------------------------------- | 1243| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1244| 16000001 | The specified ability does not exist. | 1245| 16000002 | Incorrect ability type. | 1246| 16000004 | Cannot start an invisible component. | 1247| 16000005 | The specified process does not have the permission. | 1248| 16000006 | Cross-user operations are not allowed. | 1249| 16000008 | The crowdtesting application expires. | 1250| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1251| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 1252| 16000011 | The context does not exist. | 1253| 16000012 | The application is controlled. | 1254| 16000013 | The application is controlled by EDM. | 1255| 16000019 | No matching ability is found. | 1256| 16000050 | Internal error. | 1257| 16000053 | The ability is not on the top of the UI. | 1258| 16000055 | Installation-free timed out. | 1259| 16000071 | App clone is not supported. | 1260| 16000072 | App clone or multi-instance is not supported. | 1261| 16000073 | The app clone index is invalid. | 1262| 16000076 | The app instance key is invalid. | 1263| 16000077 | The number of app instances reaches the limit. | 1264| 16000078 | The multi-instance is not supported. | 1265| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 1266| 16000080 | Creating a new instance is not supported. | 1267| 16200001 | The caller has been released. | 1268 1269**示例：** 1270 1271```ts 1272import { UIAbility, Want, StartOptions } from '@kit.AbilityKit'; 1273import { BusinessError } from '@kit.BasicServicesKit'; 1274 1275export default class EntryAbility extends UIAbility { 1276 onForeground() { 1277 let want: Want = { 1278 deviceId: '', 1279 bundleName: 'com.example.myapplication', 1280 abilityName: 'EntryAbility' 1281 }; 1282 let accountId = 100; 1283 let options: StartOptions = { 1284 displayId: 0 1285 }; 1286 1287 try { 1288 this.context.startAbilityWithAccount(want, accountId, options) 1289 .then(() => { 1290 // 执行正常业务 1291 console.info('startAbilityWithAccount succeed'); 1292 }) 1293 .catch((err: BusinessError) => { 1294 // 处理业务逻辑错误 1295 console.error(`startAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`); 1296 }); 1297 } catch (err) { 1298 // 处理入参错误异常 1299 let code = (err as BusinessError).code; 1300 let message = (err as BusinessError).message; 1301 console.error(`startAbilityWithAccount failed, code is ${code}, message is ${message}`); 1302 } 1303 } 1304} 1305``` 1306 1307### setMissionIcon 1308 1309setMissionIcon(icon: image.PixelMap, callback: AsyncCallback\<void>): void 1310 1311设置当前Ability在任务中显示的图标，图标大小最大为600M。使用callback异步回调。 1312 1313**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1314 1315**系统接口**：此接口为系统接口。 1316 1317**参数：** 1318 1319| 参数名 | 类型 | 必填 | 说明 | 1320| -------- | -------- | -------- | -------- | 1321| icon | image.PixelMap | 是 | 在最近的任务中显示的Ability图标。 | 1322| callback | AsyncCallback\<void> | 是 | 回调函数。当设置当前Ability在任务中显示的图标成功，err为undefined，否则为错误对象。 | 1323 1324**错误码：** 1325 1326以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1327 1328| 错误码ID | 错误信息 | 1329| ------- | -------------------------------- | 1330| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1331| 16000011 | The context does not exist. | 1332| 16000050 | Internal error. | 1333 1334**示例：** 1335 1336```ts 1337import { UIAbility } from '@kit.AbilityKit'; 1338import { image } from '@kit.ImageKit'; 1339import { BusinessError } from '@kit.BasicServicesKit'; 1340 1341export default class EntryAbility extends UIAbility { 1342 onForeground() { 1343 let imagePixelMap: image.PixelMap; 1344 let color = new ArrayBuffer(4 * 6 * 4); // 创建一个ArrayBuffer对象，用于存储图像像素。该对象的大小为（height * width * 4）字节。 1345 let bufferArr = new Uint8Array(color); 1346 for (let i = 0; i < bufferArr.length; i += 4) { 1347 bufferArr[i] = 255; 1348 bufferArr[i+1] = 0; 1349 bufferArr[i+2] = 122; 1350 bufferArr[i+3] = 255; 1351 } 1352 image.createPixelMap(color, { 1353 editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } 1354 }).then((data) => { 1355 imagePixelMap = data; 1356 this.context.setMissionIcon(imagePixelMap, (err: BusinessError) => { 1357 if (err.code) { 1358 console.error(`setMissionIcon failed, code is ${err.code}, message is ${err.message}`); 1359 return; 1360 } 1361 console.info('setMissionIcon succeed'); 1362 }); 1363 }).catch((err: BusinessError) => { 1364 console.error(`createPixelMap failed, code is ${err.code}, message is ${err.message}`); 1365 }); 1366 } 1367} 1368``` 1369 1370 1371### setMissionIcon 1372 1373setMissionIcon(icon: image.PixelMap): Promise\<void> 1374 1375设置当前Ability在任务中显示的图标, 图标大小最大为600M。使用Promise异步回调。 1376 1377**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1378 1379**系统接口**：此接口为系统接口。 1380 1381**参数：** 1382 1383| 参数名 | 类型 | 必填 | 说明 | 1384| -------- | -------- | -------- | -------- | 1385| icon | image.PixelMap | 是 | 在最近的任务中显示的Ability图标。 | 1386 1387**返回值：** 1388 1389| 类型 | 说明 | 1390| -------- | -------- | 1391| Promise\<void> | Promise对象，无返回结果。 | 1392 1393**错误码：** 1394 1395以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1396 1397| 错误码ID | 错误信息 | 1398| ------- | -------------------------------- | 1399| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1400| 16000011 | The context does not exist. | 1401| 16000050 | Internal error. | 1402 1403**示例：** 1404 1405```ts 1406import { UIAbility } from '@kit.AbilityKit'; 1407import { image } from '@kit.ImageKit'; 1408import { BusinessError } from '@kit.BasicServicesKit'; 1409 1410export default class EntryAbility extends UIAbility { 1411 onForeground() { 1412 let imagePixelMap: image.PixelMap; 1413 let color = new ArrayBuffer(4 * 6 * 4); // 创建一个ArrayBuffer对象，用于存储图像像素。该对象的大小为（height * width * 4）字节。 1414 let bufferArr = new Uint8Array(color); 1415 for (let i = 0; i < bufferArr.length; i += 4) { 1416 bufferArr[i] = 255; 1417 bufferArr[i+1] = 0; 1418 bufferArr[i+2] = 122; 1419 bufferArr[i+3] = 255; 1420 } 1421 image.createPixelMap(color, { 1422 editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } 1423 }).then((data) => { 1424 imagePixelMap = data; 1425 this.context.setMissionIcon(imagePixelMap) 1426 .then(() => { 1427 console.info('setMissionIcon succeed'); 1428 }) 1429 .catch((err: BusinessError) => { 1430 console.error(`setMissionIcon failed, code is ${err.code}, message is ${err.message}`); 1431 }); 1432 }).catch((err: BusinessError) => { 1433 console.error(`createPixelMap failed, code is ${err.code}, message is ${err.message}`); 1434 }); 1435 } 1436} 1437``` 1438 1439### startRecentAbility 1440 1441startRecentAbility(want: Want, callback: AsyncCallback<void>): void 1442 1443启动一个指定的Ability，如果这个Ability有多个实例，将拉起最近启动的那个实例。使用callback异步回调。仅支持在主线程调用。 1444 1445> **说明：** 1446> 1447> - 跨设备场景下，调用方与目标方必须为同一应用，且该应用需要具备ohos.permission.DISTRIBUTED_DATASYNC权限，才能启动成功。 1448> 1449> - 跨应用场景下，目标Ability的visible属性若配置为false，调用方应用需申请ohos.permission.START_INVISIBLE_ABILITY权限。 1450> 1451> - 如果指定的Ability有多个实例，调用方应用需申请ohos.permission.START_RECENT_ABILITY权限（该权限仅系统应用可申请），才能拉起最近启动的那个实例。 1452> 1453> - 如果调用方位于后台，还需要具备ohos.permission.START_ABILITIES_FROM_BACKGROUND（该权限仅系统应用可申请）。 1454 1455更多的组件启动规则详见[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 1456 1457**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1458 1459**系统接口**：此接口为系统接口。 1460 1461**参数：** 1462 1463| 参数名 | 类型 | 必填 | 说明 | 1464| -------- | -------- | -------- | -------- | 1465| want | [Want](js-apis-app-ability-want.md) | 是 | 需要启动Ability的want信息。 | 1466| callback | AsyncCallback\<void> | 是 | 指定的回调函数的结果。 | 1467 1468**错误码：** 1469 1470以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1471 1472| 错误码ID | 错误信息 | 1473| ------- | -------------------------------- | 1474| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1475| 16000001 | The specified ability does not exist. | 1476| 16000002 | Incorrect ability type. | 1477| 16000004 | Cannot start an invisible component. | 1478| 16000005 | The specified process does not have the permission. | 1479| 16000006 | Cross-user operations are not allowed. | 1480| 16000008 | The crowdtesting application expires. | 1481| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1482| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 1483| 16000011 | The context does not exist. | 1484| 16000012 | The application is controlled. | 1485| 16000013 | The application is controlled by EDM. | 1486| 16000050 | Internal error. | 1487| 16000053 | The ability is not on the top of the UI. | 1488| 16000055 | Installation-free timed out. | 1489| 16000071 | App clone is not supported. | 1490| 16000072 | App clone or multi-instance is not supported. | 1491| 16000073 | The app clone index is invalid. | 1492| 16000076 | The app instance key is invalid. | 1493| 16000077 | The number of app instances reaches the limit. | 1494| 16000078 | The multi-instance is not supported. | 1495| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 1496| 16000080 | Creating a new instance is not supported. | 1497| 16200001 | The caller has been released. | 1498 1499**示例：** 1500 1501```ts 1502import { UIAbility, Want } from '@kit.AbilityKit'; 1503import { BusinessError } from '@kit.BasicServicesKit'; 1504 1505export default class EntryAbility extends UIAbility { 1506 onForeground() { 1507 let want: Want = { 1508 bundleName: 'com.example.myapplication', 1509 abilityName: 'EntryAbility' 1510 }; 1511 1512 try { 1513 this.context.startRecentAbility(want, (err: BusinessError) => { 1514 if (err.code) { 1515 // 处理业务逻辑错误 1516 console.error(`startRecentAbility failed, code is ${err.code}, message is ${err.message}`); 1517 return; 1518 } 1519 // 执行正常业务 1520 console.info('startRecentAbility succeed'); 1521 }); 1522 } catch (err) { 1523 // 处理入参错误异常 1524 let code = (err as BusinessError).code; 1525 let message = (err as BusinessError).message; 1526 console.error(`startRecentAbility failed, code is ${code}, message is ${message}`); 1527 } 1528 } 1529} 1530``` 1531### startRecentAbility 1532 1533startRecentAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void 1534 1535启动一个指定的Ability。如果这个Ability有多个实例，将拉起最近启动的那个实例。当开发者需要携带启动参数时可以选择此API。使用callback异步回调。仅支持在主线程调用。 1536 1537> **说明：** 1538> 1539> - 跨设备场景下，调用方与目标方必须为同一应用，且该应用需要具备ohos.permission.DISTRIBUTED_DATASYNC权限，才能启动成功。 1540> 1541> - 跨应用场景下，目标Ability的visible属性若配置为false，调用方应用需申请ohos.permission.START_INVISIBLE_ABILITY权限。 1542> 1543> - 如果指定的Ability有多个实例，调用方应用需申请ohos.permission.START_RECENT_ABILITY权限（该权限仅系统应用可申请），才能拉起最近启动的那个实例。 1544> 1545> - 如果调用方位于后台，还需要具备ohos.permission.START_ABILITIES_FROM_BACKGROUND（该权限仅系统应用可申请）。 1546 1547更多的组件启动规则详见[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 1548 1549**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1550 1551**系统接口**：此接口为系统接口。 1552 1553**参数：** 1554 1555| 参数名 | 类型 | 必填 | 说明 | 1556| -------- | -------- | -------- | -------- | 1557| want | [Want](js-apis-app-ability-want.md) | 是 | 需要启动Ability的want信息。 | 1558| options | [StartOptions](js-apis-app-ability-startOptions.md) | 是 | 启动Ability所携带的参数。 | 1559| callback | AsyncCallback\<void> | 是 | 指定的回调函数的结果。 | 1560 1561**错误码：** 1562 1563以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1564 1565| 错误码ID | 错误信息 | 1566| ------- | -------------------------------- | 1567| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1568| 16000001 | The specified ability does not exist. | 1569| 16000004 | Cannot start an invisible component. | 1570| 16000005 | The specified process does not have the permission. | 1571| 16000006 | Cross-user operations are not allowed. | 1572| 16000008 | The crowdtesting application expires. | 1573| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1574| 16000011 | The context does not exist. | 1575| 16000012 | The application is controlled. | 1576| 16000013 | The application is controlled by EDM. | 1577| 16000050 | Internal error. | 1578| 16000053 | The ability is not on the top of the UI. | 1579| 16000055 | Installation-free timed out. | 1580| 16000071 | App clone is not supported. | 1581| 16000072 | App clone or multi-instance is not supported. | 1582| 16000073 | The app clone index is invalid. | 1583| 16000076 | The app instance key is invalid. | 1584| 16000077 | The number of app instances reaches the limit. | 1585| 16000078 | The multi-instance is not supported. | 1586| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 1587| 16000080 | Creating a new instance is not supported. | 1588| 16200001 | The caller has been released. | 1589 1590**示例：** 1591 1592```ts 1593import { UIAbility, Want, StartOptions } from '@kit.AbilityKit'; 1594import { BusinessError } from '@kit.BasicServicesKit'; 1595 1596export default class EntryAbility extends UIAbility { 1597 onForeground() { 1598 let want: Want = { 1599 deviceId: '', 1600 bundleName: 'com.example.myapplication', 1601 abilityName: 'EntryAbility' 1602 }; 1603 let options: StartOptions = { 1604 displayId: 0 1605 }; 1606 1607 try { 1608 this.context.startRecentAbility(want, options, (err: BusinessError) => { 1609 if (err.code) { 1610 // 处理业务逻辑错误 1611 console.error(`startRecentAbility failed, code is ${err.code}, message is ${err.message}`); 1612 return; 1613 } 1614 // 执行正常业务 1615 console.info('startRecentAbility succeed'); 1616 }); 1617 } catch (err) { 1618 // 处理入参错误异常 1619 let code = (err as BusinessError).code; 1620 let message = (err as BusinessError).message; 1621 console.error(`startRecentAbility failed, code is ${code}, message is ${message}`); 1622 } 1623 } 1624} 1625``` 1626### startRecentAbility 1627 1628startRecentAbility(want: Want, options?: StartOptions): Promise<void> 1629 1630启动一个指定的Ability。如果这个Ability有多个实例，将拉起最近启动的那个实例。使用Promise异步回调。仅支持在主线程调用。 1631 1632> **说明：** 1633> 1634> - 跨设备场景下，调用方与目标方必须为同一应用，且该应用需要具备ohos.permission.DISTRIBUTED_DATASYNC权限，才能启动成功。 1635> 1636> - 跨应用场景下，目标Ability的visible属性若配置为false，调用方应用需申请ohos.permission.START_INVISIBLE_ABILITY权限。 1637> 1638> - 如果指定的Ability有多个实例，调用方应用需申请ohos.permission.START_RECENT_ABILITY权限（该权限仅系统应用可申请），才能拉起最近启动的那个实例。 1639> 1640> - 如果调用方位于后台，还需要具备ohos.permission.START_ABILITIES_FROM_BACKGROUND（该权限仅系统应用可申请）。 1641 1642更多的组件启动规则详见[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 1643 1644**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1645 1646**系统接口**：此接口为系统接口。 1647 1648**参数：** 1649 1650| 参数名 | 类型 | 必填 | 说明 | 1651| -------- | -------- | -------- | -------- | 1652| want | [Want](js-apis-app-ability-want.md) | 是 | 需要启动Ability的want信息。 | 1653| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否 | 启动Ability所携带的参数。 | 1654 1655**返回值：** 1656 1657| 类型 | 说明 | 1658| -------- | -------- | 1659| Promise\<void> | Promise对象，无返回结果。 | 1660 1661**错误码：** 1662 1663以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1664 1665| 错误码ID | 错误信息 | 1666| ------- | -------------------------------- | 1667| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1668| 16000001 | The specified ability does not exist. | 1669| 16000002 | Incorrect ability type. | 1670| 16000004 | Cannot start an invisible component. | 1671| 16000005 | The specified process does not have the permission. | 1672| 16000006 | Cross-user operations are not allowed. | 1673| 16000008 | The crowdtesting application expires. | 1674| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1675| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 1676| 16000011 | The context does not exist. | 1677| 16000012 | The application is controlled. | 1678| 16000013 | The application is controlled by EDM. | 1679| 16000050 | Internal error. | 1680| 16000053 | The ability is not on the top of the UI. | 1681| 16000055 | Installation-free timed out. | 1682| 16000071 | App clone is not supported. | 1683| 16000072 | App clone or multi-instance is not supported. | 1684| 16000073 | The app clone index is invalid. | 1685| 16000076 | The app instance key is invalid. | 1686| 16000077 | The number of app instances reaches the limit. | 1687| 16000078 | The multi-instance is not supported. | 1688| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 1689| 16000080 | Creating a new instance is not supported. | 1690| 16200001 | The caller has been released. | 1691 1692**示例：** 1693 1694```ts 1695import { UIAbility, Want, StartOptions } from '@kit.AbilityKit'; 1696import { BusinessError } from '@kit.BasicServicesKit'; 1697 1698export default class EntryAbility extends UIAbility { 1699 onForeground() { 1700 let want: Want = { 1701 bundleName: 'com.example.myapplication', 1702 abilityName: 'EntryAbility' 1703 }; 1704 let options: StartOptions = { 1705 displayId: 0, 1706 }; 1707 1708 try { 1709 this.context.startRecentAbility(want, options) 1710 .then(() => { 1711 // 执行正常业务 1712 console.info('startRecentAbility succeed'); 1713 }) 1714 .catch((err: BusinessError) => { 1715 // 处理业务逻辑错误 1716 console.error(`startRecentAbility failed, code is ${err.code}, message is ${err.message}`); 1717 }); 1718 } catch (err) { 1719 // 处理入参错误异常 1720 let code = (err as BusinessError).code; 1721 let message = (err as BusinessError).message; 1722 console.error(`startRecentAbility failed, code is ${code}, message is ${message}`); 1723 } 1724 } 1725} 1726``` 1727 1728### startAbilityByCallWithAccount<sup>10+</sup> 1729 1730startAbilityByCallWithAccount(want: Want, accountId: number): Promise<Caller> 1731 1732根据accountId对指定的Ability进行call调用，并且可以使用返回的Caller通信接口与被调用方进行通信。仅支持在主线程调用。 1733该接口不支持拉起启动模式为[specified模式](../../application-models/uiability-launch-type.md#specified启动模式)的UIAbility。 1734 1735使用规则： 1736 - 跨用户场景下，Call调用目标Ability时，调用方应用需同时申请`ohos.permission.ABILITY_BACKGROUND_COMMUNICATION`与`ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS`权限。 1737 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限。 1738 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限。 1739 - 同设备与跨设备场景下，该接口的使用规则存在差异，详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 1740 1741**需要权限**：ohos.permission.ABILITY_BACKGROUND_COMMUNICATION, ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 1742 1743**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1744 1745**系统接口**：此接口为系统接口。 1746 1747**参数：** 1748 1749| 参数名 | 类型 | 必填 | 说明 | 1750| -------- | -------- | -------- | -------- | 1751| want | [Want](js-apis-app-ability-want.md) | 是 | 传入需要启动的Ability的信息，包含abilityName、moduleName、bundleName、deviceId(可选)、parameters(可选)，其中deviceId缺省或为空表示启动本地Ability，parameters缺省或为空表示后台启动Ability。 | 1752| accountId | number | 是 | 系统账号的账号ID，-1表示当前活动用户，详情参考[getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getosaccountcount9)。 | 1753 1754**返回值：** 1755 1756| 类型 | 说明 | 1757| -------- | -------- | 1758| Promise<[Caller](js-apis-app-ability-uiAbility.md#caller)> | 获取要通讯的caller对象。 | 1759 1760**错误码：** 1761 1762以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1763 1764| 错误码ID | 错误信息 | 1765| ------- | -------------------------------- | 1766| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1767| 16000001 | The specified ability does not exist. | 1768| 16000002 | Incorrect ability type. | 1769| 16000004 | Cannot start an invisible component. | 1770| 16000005 | The specified process does not have the permission. | 1771| 16000006 | Cross-user operations are not allowed. | 1772| 16000008 | The crowdtesting application expires. | 1773| 16000011 | The context does not exist. | 1774| 16000012 | The application is controlled. | 1775| 16000013 | The application is controlled by EDM. | 1776| 16000050 | Internal error. | 1777| 16000071 | App clone is not supported. | 1778| 16000072 | App clone or multi-instance is not supported. | 1779| 16000073 | The app clone index is invalid. | 1780| 16000076 | The app instance key is invalid. | 1781| 16000077 | The number of app instances reaches the limit. | 1782| 16000078 | The multi-instance is not supported. | 1783| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 1784| 16000080 | Creating a new instance is not supported. | 1785| 16200001 | The caller has been released. | 1786 1787**示例：** 1788 1789```ts 1790import { UIAbility, Want, Caller } from '@kit.AbilityKit'; 1791import { BusinessError } from '@kit.BasicServicesKit'; 1792 1793export default class EntryAbility extends UIAbility { 1794 onForeground() { 1795 let caller: Caller; 1796 // 系统账号的账号ID, -1表示当前激活用户 1797 let accountId = -1; 1798 // 指定启动的Ability 1799 let want: Want = { 1800 bundleName: 'com.acts.actscalleeabilityrely', 1801 moduleName: 'entry', 1802 abilityName: 'EntryAbility', 1803 deviceId: '', 1804 parameters: { 1805 // 'ohos.aafwk.param.callAbilityToForeground' 值设置为true时为前台启动, 设置false或不设置为后台启动 1806 'ohos.aafwk.param.callAbilityToForeground': true 1807 } 1808 }; 1809 1810 try { 1811 this.context.startAbilityByCallWithAccount(want, accountId) 1812 .then((obj: Caller) => { 1813 // 执行正常业务 1814 caller = obj; 1815 console.info('startAbilityByCallWithAccount succeed'); 1816 }).catch((error: BusinessError) => { 1817 // 处理业务逻辑错误 1818 console.error(`startAbilityByCallWithAccount failed, error.code: ${error.code}, error.message: ${error.message}`); 1819 }); 1820 } catch (paramError) { 1821 // 处理入参错误异常 1822 console.error(`error.code: ${paramError.code}, error.message: ${paramError.message}`); 1823 } 1824 } 1825} 1826``` 1827 1828### startAbilityAsCaller<sup>10+<sup> 1829 1830startAbilityAsCaller(want: Want, callback: AsyncCallback\<void>): void 1831 1832使用设置的caller信息启动一个Ability，caller信息由want携带，在系统服务层识别，Ability可以在onCreate生命周期的want参数中获取到caller信息。使用该接口启动一个Ability时，want的caller信息不会被当前自身的应用信息覆盖，系统服务层可获取到初始caller的信息。使用callback异步回调。仅支持在主线程调用。 1833 1834> **说明：** 1835> 1836> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 1837 1838**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1839 1840**系统接口**：此接口为系统接口。 1841 1842**参数：** 1843 1844| 参数名 | 类型 | 必填 | 说明 | 1845| -------- | -------- | -------- | -------- | 1846| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 1847| callback | AsyncCallback<void> | 是 | 回调函数。当启动Ability成功，err为undefined，否则为错误对象。 | 1848 1849**错误码：** 1850 1851以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1852 1853| 错误码ID | 错误信息 | 1854| ------- | -------------------------------- | 1855| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1856| 16000001 | The specified ability does not exist. | 1857| 16000002 | Incorrect ability type. | 1858| 16000004 | Cannot start an invisible component. | 1859| 16000005 | The specified process does not have the permission. | 1860| 16000006 | Cross-user operations are not allowed. | 1861| 16000008 | The crowdtesting application expires. | 1862| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1863| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 1864| 16000011 | The context does not exist. | 1865| 16000012 | The application is controlled. | 1866| 16000013 | The application is controlled by EDM. | 1867| 16000050 | Internal error. | 1868| 16000053 | The ability is not on the top of the UI. | 1869| 16000055 | Installation-free timed out. | 1870| 16000071 | App clone is not supported. | 1871| 16000072 | App clone or multi-instance is not supported. | 1872| 16000073 | The app clone index is invalid. | 1873| 16000076 | The app instance key is invalid. | 1874| 16000077 | The number of app instances reaches the limit. | 1875| 16000078 | The multi-instance is not supported. | 1876| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 1877| 16000080 | Creating a new instance is not supported. | 1878| 16200001 | The caller has been released. | 1879 1880**示例：** 1881 1882```ts 1883import { UIAbility, Want, AbilityConstant } from '@kit.AbilityKit'; 1884 1885export default class EntryAbility extends UIAbility { 1886 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 1887 // want包含启动该应用的Caller信息 1888 let localWant: Want = want; 1889 localWant.bundleName = 'com.example.demo'; 1890 localWant.moduleName = 'entry'; 1891 localWant.abilityName = 'TestAbility'; 1892 1893 // 使用启动方的Caller身份信息启动新Ability 1894 this.context.startAbilityAsCaller(localWant, (err) => { 1895 if (err && err.code != 0) { 1896 console.error(`startAbilityAsCaller failed, code is ${err.code}, message is ${err.message}`); 1897 } else { 1898 console.info('startAbilityAsCaller success.'); 1899 } 1900 }); 1901 } 1902} 1903``` 1904 1905### startAbilityAsCaller<sup>10+<sup> 1906 1907startAbilityAsCaller(want: Want, options: StartOptions, callback: AsyncCallback\<void>): void 1908 1909使用设置的caller信息启动一个Ability，caller信息由want携带，在系统服务层识别，Ability可以在onCreate生命周期的want参数中获取到caller信息。使用该接口启动一个Ability时，want的caller信息不会被当前自身的应用信息覆盖，系统服务层可获取到初始caller的信息。使用callback异步回调。仅支持在主线程调用。 1910 1911> **说明：** 1912> 1913> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 1914 1915**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1916 1917**系统接口**：此接口为系统接口。 1918 1919**参数：** 1920 1921| 参数名 | 类型 | 必填 | 说明 | 1922| -------- | -------- | -------- | -------- | 1923| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 1924| options | [StartOptions](js-apis-app-ability-startOptions.md) | 是 | 启动Ability所携带的参数。 | 1925| callback | AsyncCallback<void> | 是 | 回调函数。当启动Ability成功，err为undefined，否则为错误对象。 | 1926 1927**错误码：** 1928 1929以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1930 1931| 错误码ID | 错误信息 | 1932| ------- | -------------------------------- | 1933| 401 | 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 1934| 16000001 | The specified ability does not exist. | 1935| 16000004 | Cannot start an invisible component. | 1936| 16000005 | The specified process does not have the permission. | 1937| 16000006 | Cross-user operations are not allowed. | 1938| 16000008 | The crowdtesting application expires. | 1939| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1940| 16000011 | The context does not exist. | 1941| 16000012 | The application is controlled. | 1942| 16000013 | The application is controlled by EDM. | 1943| 16000050 | Internal error. | 1944| 16000053 | The ability is not on the top of the UI. | 1945| 16000055 | Installation-free timed out. | 1946| 16000071 | App clone is not supported. | 1947| 16000072 | App clone or multi-instance is not supported. | 1948| 16000073 | The app clone index is invalid. | 1949| 16000076 | The app instance key is invalid. | 1950| 16000077 | The number of app instances reaches the limit. | 1951| 16000078 | The multi-instance is not supported. | 1952| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 1953| 16000080 | Creating a new instance is not supported. | 1954| 16200001 | The caller has been released. | 1955 1956**示例：** 1957 1958```ts 1959import { UIAbility, Want, AbilityConstant, StartOptions } from '@kit.AbilityKit'; 1960 1961export default class EntryAbility extends UIAbility { 1962 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 1963 // want包含启动该应用的Caller信息 1964 let localWant: Want = want; 1965 localWant.bundleName = 'com.example.demo'; 1966 localWant.moduleName = 'entry'; 1967 localWant.abilityName = 'TestAbility'; 1968 let option: StartOptions = { 1969 displayId: 0 1970 }; 1971 1972 // 使用启动方的Caller身份信息启动新Ability 1973 this.context.startAbilityAsCaller(localWant, option, (err) => { 1974 if (err && err.code != 0) { 1975 console.error(`startAbilityAsCaller failed, code is ${err.code}, message is ${err.message}`); 1976 } else { 1977 console.info('startAbilityAsCaller success.'); 1978 } 1979 }); 1980 } 1981} 1982``` 1983 1984### startAbilityAsCaller<sup>10+<sup> 1985 1986startAbilityAsCaller(want: Want, options?: StartOptions): Promise\<void> 1987 1988使用设置的caller信息启动一个Ability，caller信息由want携带，在系统服务层识别，Ability可以在onCreate生命周期的want参数中获取到caller信息。使用该接口启动一个Ability时，want的caller信息不会被当前自身的应用信息覆盖，系统服务层可获取到初始caller的信息。使用Promise异步回调。仅支持在主线程调用。 1989 1990> **说明：** 1991> 1992> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 1993 1994**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1995 1996**系统接口**：此接口为系统接口。 1997 1998**参数：** 1999 2000| 参数名 | 类型 | 必填 | 说明 | 2001| -------- | -------- | -------- | -------- | 2002| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 2003| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否 | 启动Ability所携带的参数。 | 2004 2005**返回值：** 2006 2007| 类型 | 说明 | 2008| -------- | -------- | 2009| Promise\<void> | Promise对象，无返回结果。 | 2010 2011**错误码：** 2012 2013以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 2014 2015| 错误码ID | 错误信息 | 2016| ------- | -------------------------------- | 2017| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2018| 16000001 | The specified ability does not exist. | 2019| 16000002 | Incorrect ability type. | 2020| 16000004 | Cannot start an invisible component. | 2021| 16000005 | The specified process does not have the permission. | 2022| 16000006 | Cross-user operations are not allowed. | 2023| 16000008 | The crowdtesting application expires. | 2024| 16000009 | An ability cannot be started or stopped in Wukong mode. | 2025| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 2026| 16000011 | The context does not exist. | 2027| 16000012 | The application is controlled. | 2028| 16000013 | The application is controlled by EDM. | 2029| 16000050 | Internal error. | 2030| 16000053 | The ability is not on the top of the UI. | 2031| 16000055 | Installation-free timed out. | 2032| 16000071 | App clone is not supported. | 2033| 16000072 | App clone or multi-instance is not supported. | 2034| 16000073 | The app clone index is invalid. | 2035| 16000076 | The app instance key is invalid. | 2036| 16000077 | The number of app instances reaches the limit. | 2037| 16000078 | The multi-instance is not supported. | 2038| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 2039| 16000080 | Creating a new instance is not supported. | 2040| 16200001 | The caller has been released. | 2041 2042**示例：** 2043 2044```ts 2045import { UIAbility, Want, AbilityConstant, StartOptions } from '@kit.AbilityKit'; 2046import { BusinessError } from '@kit.BasicServicesKit'; 2047 2048export default class EntryAbility extends UIAbility { 2049 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 2050 // want包含启动该应用的Caller信息 2051 let localWant: Want = want; 2052 localWant.bundleName = 'com.example.demo'; 2053 localWant.moduleName = 'entry'; 2054 localWant.abilityName = 'TestAbility'; 2055 let option: StartOptions = { 2056 displayId: 0 2057 }; 2058 2059 // 使用启动方的Caller身份信息启动新Ability 2060 this.context.startAbilityAsCaller(localWant, option) 2061 .then(() => { 2062 console.info('startAbilityAsCaller success.'); 2063 }) 2064 .catch((err: BusinessError) => { 2065 console.error(`startAbilityAsCaller failed, code is ${err.code}, message is ${err.message}`); 2066 }); 2067 } 2068} 2069``` 2070 2071### requestModalUIExtension<sup>11+<sup> 2072 2073requestModalUIExtension(pickerWant: Want): Promise\<void> 2074 2075请求在指定的前台应用上拉起对应类型的UIExtensionAbility。使用Promise异步回调。仅支持在主线程调用。 2076 2077其中，前台应用通过want.parameters中bundleName来指定，如果未指定前台应用、bundleName指定的应用未在前台或指定的前台应用的bundleName不正确，则在系统界面上直接拉起UIExtensionAbility；被拉起的UIExtensionAbility通过want中bundleName、abilityName、moduleName字段共同确定，同时需要通过want.parameters中的ability.want.params.uiExtensionType字段配置UIExtensionAbility的类型。 2078 2079在前台应用上拉起UIExtensionAbility之前，必须确保该应用已完成页面初始化，否则将导致拉起失败、并出现"uiContent is nullptr"的报错信息。应用可通过监听页面加载状态来判断拉起UIExtensionAbility的时机，页面初始化成功后会出现关键日志信息"UIContentImpl: focus again"。 2080 2081> **说明：** 2082> 2083> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 2084 2085**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 2086 2087**系统接口**：此接口为系统接口。 2088 2089**参数：** 2090 2091| 参数名 | 类型 | 必填 | 说明 | 2092| -------- | -------- | -------- | -------- | 2093| pickerWant | [Want](js-apis-app-ability-want.md) | 是 | 拉起UIExtension的want信息。 | 2094 2095**返回值：** 2096 2097| 类型 | 说明 | 2098| -------- | -------- | 2099| Promise\<void> | Promise对象，无返回结果。 | 2100 2101**错误码：** 2102 2103以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 2104 2105| 错误码ID | 错误信息 | 2106| ------- | -------------------------------- | 2107| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 2108| 16000050 | Internal error. | 2109 2110**示例：** 2111 2112```ts 2113import { UIAbility, Want } from '@kit.AbilityKit'; 2114import { BusinessError } from '@kit.BasicServicesKit'; 2115 2116export default class EntryAbility extends UIAbility { 2117 onForeground() { 2118 let want: Want = { 2119 bundleName: 'com.example.myapplication', 2120 abilityName: 'com.example.myapplication.UIExtAbility', 2121 moduleName: 'entry_test', 2122 parameters: { 2123 'bundleName': 'com.example.myapplication', 2124 //与com.example.myapplication.UIExtAbility配置的type相同 2125 'ability.want.params.uiExtensionType': 'sys/commonUI' 2126 } 2127 }; 2128 2129 try { 2130 this.context.requestModalUIExtension(want) 2131 .then(() => { 2132 // 执行正常业务 2133 console.info('requestModalUIExtension succeed'); 2134 }) 2135 .catch((err: BusinessError) => { 2136 // 处理业务逻辑错误 2137 console.error(`requestModalUIExtension failed, code is ${err.code}, message is ${err.message}`); 2138 }); 2139 } catch (err) { 2140 // 处理入参错误异常 2141 let code = (err as BusinessError).code; 2142 let message = (err as BusinessError).message; 2143 console.error(`requestModalUIExtension failed, code is ${code}, message is ${message}`); 2144 } 2145 } 2146} 2147``` 2148 2149### requestModalUIExtension<sup>11+<sup> 2150requestModalUIExtension(pickerWant: Want, callback: AsyncCallback\<void>): void 2151 2152请求在指定的前台应用上拉起对应类型的UIExtensionAbility。使用callback异步回调。仅支持在主线程调用。 2153 2154其中，前台应用通过want.parameters中bundleName来指定，如果未指定前台应用、bundleName指定的应用未在前台或指定的前台应用的bundleName不正确，则在系统界面上直接拉起UIExtensionAbility；被拉起的UIExtensionAbility通过want中bundleName、abilityName、moduleName字段共同确定，同时需要通过want.parameters中的ability.want.params.uiExtensionType字段配置UIExtensionAbility的类型。 2155 2156在前台应用上拉起UIExtensionAbility之前，必须确保该应用已完成页面初始化，否则将导致拉起失败、并出现"uiContent is nullptr"的报错信息。应用可通过监听页面加载状态来判断拉起UIExtensionAbility的时机，页面初始化成功后会出现关键日志信息"UIContentImpl: focus again"。 2157 2158> **说明：** 2159> 2160> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 2161 2162**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 2163 2164**系统接口**：此接口为系统接口。 2165 2166**参数：** 2167 2168| 参数名 | 类型 | 必填 | 说明 | 2169| -------- | -------- | -------- | -------- | 2170| pickerWant | [Want](js-apis-app-ability-want.md) | 是 | 拉起UIExtension的want信息。 | 2171| callback | AsyncCallback<void> | 是 | 回调函数。当拉起UIExtension成功，err为undefined，否则为错误对象。 | 2172 2173**错误码：** 2174 2175以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 2176 2177| 错误码ID | 错误信息 | 2178| ------- | -------------------------------- | 2179| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 2180| 16000050 | Internal error. | 2181 2182**示例：** 2183 2184```ts 2185import { UIAbility, Want } from '@kit.AbilityKit'; 2186import { BusinessError } from '@kit.BasicServicesKit'; 2187 2188export default class EntryAbility extends UIAbility { 2189 onForeground() { 2190 let want: Want = { 2191 bundleName: 'com.example.myapplication', 2192 abilityName: 'UIExtAbility', 2193 moduleName: 'entry_test', 2194 parameters: { 2195 'bundleName': 'com.example.myapplication', 2196 //与com.example.myapplication.UIExtAbility配置的type相同 2197 'ability.want.params.uiExtensionType': 'sys/commonUI' 2198 } 2199 }; 2200 2201 try { 2202 this.context.requestModalUIExtension(want, (err: BusinessError) => { 2203 if (err.code) { 2204 // 处理业务逻辑错误 2205 console.error(`requestModalUIExtension failed, code is ${err.code}, message is ${err.message}`); 2206 return; 2207 } 2208 // 执行正常业务 2209 console.info('requestModalUIExtension succeed'); 2210 }); 2211 } catch (err) { 2212 // 处理入参错误异常 2213 let code = (err as BusinessError).code; 2214 let message = (err as BusinessError).message; 2215 console.error(`requestModalUIExtension failed, code is ${code}, message is ${message}`); 2216 } 2217 } 2218} 2219``` 2220