1# UIAbilityContext 2 3**UIAbilityContext**, inherited from [Context](js-apis-inner-application-context.md), provides the context environment for [UIAbility](js-apis-app-ability-uiAbility.md) that needs to store its status. **UIAbilityContext** provides UIAbility-related configuration and APIs for operating UIAbilities and ServiceExtensionAbilities. For example, you can use the APIs to start a UIAbility, terminate a UIAbility to which the UIAbilityContext belongs, and start, terminate, connect to, or disconnect from a ServiceExtensionAbility. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> - The APIs of this module can be used only in the stage model. 9> - The APIs of this module must be used in the main thread, but not in sub-threads such as Worker and TaskPool. 10 11## Modules to Import 12 13```ts 14import common from '@ohos.app.ability.common'; 15``` 16 17## Attributes 18 19**System capability**: SystemCapability.Ability.AbilityRuntime.Core 20 21| Name| Type| Readable| Writable| Description| 22| -------- | -------- | -------- | -------- | -------- | 23| abilityInfo | [AbilityInfo](js-apis-bundleManager-abilityInfo.md) | Yes| No| UIAbility information.| 24| currentHapModuleInfo | [HapModuleInfo](js-apis-bundleManager-hapModuleInfo.md) | Yes| No| HAP information.| 25| config | [Configuration](js-apis-app-ability-configuration.md) | Yes| No| UIAbility configuration, such as the language and color mode.| 26 27> **NOTE** 28> 29> In the sample code provided in this topic, **this.context** is used to obtain **UIAbilityContext**, where **this** indicates a UIAbility instance inherited from **UIAbility**. To use **UIAbilityContext** APIs on pages, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 30 31## UIAbilityContext.startAbility 32 33startAbility(want: Want, callback: AsyncCallback<void>): void 34 35Starts an ability. This API uses an asynchronous callback to return the result. 36 37Observe the following when using this API: 38 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 39 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 40 - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 41 - If the ability to start is in another mission stack and the result needs to be returned to the caller, set the **want** parameter by following the description provided in [Want](js-apis-app-ability-want.md). 42 43**System capability**: SystemCapability.Ability.AbilityRuntime.Core 44 45**Parameters** 46 47| Name| Type| Mandatory| Description| 48| -------- | -------- | -------- | -------- | 49| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 50| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 51 52**Error codes** 53 54| ID| Error Message| 55| ------- | -------------------------------- | 56| 16000001 | The specified ability does not exist. | 57| 16000002 | Incorrect ability type. | 58| 16000004 | Can not start invisible component. | 59| 16000005 | The specified process does not have the permission. | 60| 16000006 | Cross-user operations are not allowed. | 61| 16000008 | The crowdtesting application expires. | 62| 16000009 | An ability cannot be started or stopped in Wukong mode. | 63| 16000010 | The call with the continuation flag is forbidden. | 64| 16000011 | The context does not exist. | 65| 16000012 | The application is controlled. | 66| 16000013 | The application is controlled by EDM. | 67| 16000050 | Internal error. | 68| 16000053 | The ability is not on the top of the UI. | 69| 16000055 | Installation-free timed out. | 70| 16200001 | The caller has been released. | 71 72For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 73 74**Example** 75 76```ts 77import UIAbility from '@ohos.app.ability.UIAbility'; 78import Want from '@ohos.app.ability.Want'; 79import { BusinessError } from '@ohos.base'; 80 81export default class EntryAbility extends UIAbility { 82 83 onForeground() { 84 let want: Want = { 85 bundleName: 'com.example.myapplication', 86 abilityName: 'EntryAbility' 87 }; 88 89 try { 90 this.context.startAbility(want, (err: BusinessError) => { 91 if (err.code) { 92 // Process service logic errors. 93 console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`); 94 return; 95 } 96 // Carry out normal service processing. 97 console.info('startAbility succeed'); 98 }); 99 } catch (err) { 100 // Process input parameter errors. 101 let code = (err as BusinessError).code; 102 let message = (err as BusinessError).message; 103 console.error(`startAbility failed, code is ${code}, message is ${message}`); 104 } 105 } 106} 107``` 108 109## UIAbilityContext.startAbility 110 111startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void 112 113Starts an ability with the start options specified. This API uses an asynchronous callback to return the result. 114 115Observe the following when using this API: 116 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 117 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 118 - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 119 120**System capability**: SystemCapability.Ability.AbilityRuntime.Core 121 122**Parameters** 123 124| Name| Type| Mandatory| Description| 125| -------- | -------- | -------- | -------- | 126| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 127| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| 128| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 129 130**Error codes** 131 132| ID| Error Message| 133| ------- | -------------------------------- | 134| 16000001 | The specified ability does not exist. | 135| 16000002 | Incorrect ability type. | 136| 16000004 | Can not start invisible component. | 137| 16000005 | The specified process does not have the permission. | 138| 16000006 | Cross-user operations are not allowed. | 139| 16000008 | The crowdtesting application expires. | 140| 16000009 | An ability cannot be started or stopped in Wukong mode. | 141| 16000010 | The call with the continuation flag is forbidden. | 142| 16000011 | The context does not exist. | 143| 16000012 | The application is controlled. | 144| 16000013 | The application is controlled by EDM. | 145| 16000050 | Internal error. | 146| 16000053 | The ability is not on the top of the UI. | 147| 16000055 | Installation-free timed out. | 148| 16200001 | The caller has been released. | 149 150For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 151 152**Example** 153 154```ts 155import UIAbility from '@ohos.app.ability.UIAbility'; 156import Want from '@ohos.app.ability.Want'; 157import StartOptions from '@ohos.app.ability.StartOptions'; 158import { BusinessError } from '@ohos.base'; 159 160export default class EntryAbility extends UIAbility { 161 162 onForeground() { 163 let want: Want = { 164 deviceId: '', 165 bundleName: 'com.example.myapplication', 166 abilityName: 'EntryAbility' 167 }; 168 let options: StartOptions = { 169 windowMode: 0 170 }; 171 172 try { 173 this.context.startAbility(want, options, (err: BusinessError) => { 174 if (err.code) { 175 // Process service logic errors. 176 console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`); 177 return; 178 } 179 // Carry out normal service processing. 180 console.info('startAbility succeed'); 181 }); 182 } catch (err) { 183 // Process input parameter errors. 184 let code = (err as BusinessError).code; 185 let message = (err as BusinessError).message; 186 console.error(`startAbility failed, code is ${code}, message is ${message}`); 187 } 188 } 189} 190``` 191 192## UIAbilityContext.startAbility 193 194startAbility(want: Want, options?: StartOptions): Promise<void> 195 196Starts an ability. This API uses a promise to return the result. 197 198Observe the following when using this API: 199 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 200 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 201 - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 202 203**System capability**: SystemCapability.Ability.AbilityRuntime.Core 204 205**Parameters** 206 207| Name| Type| Mandatory| Description| 208| -------- | -------- | -------- | -------- | 209| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 210| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| 211 212**Return value** 213 214| Type| Description| 215| -------- | -------- | 216| Promise<void> | Promise used to return the result.| 217 218**Error codes** 219 220| ID| Error Message| 221| ------- | -------------------------------- | 222| 16000001 | The specified ability does not exist. | 223| 16000002 | Incorrect ability type. | 224| 16000004 | Can not start invisible component. | 225| 16000005 | The specified process does not have the permission. | 226| 16000006 | Cross-user operations are not allowed. | 227| 16000008 | The crowdtesting application expires. | 228| 16000009 | An ability cannot be started or stopped in Wukong mode. | 229| 16000010 | The call with the continuation flag is forbidden. | 230| 16000011 | The context does not exist. | 231| 16000012 | The application is controlled. | 232| 16000013 | The application is controlled by EDM. | 233| 16000050 | Internal error. | 234| 16000053 | The ability is not on the top of the UI. | 235| 16000055 | Installation-free timed out. | 236| 16200001 | The caller has been released. | 237 238For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 239 240**Example** 241 242```ts 243import UIAbility from '@ohos.app.ability.UIAbility'; 244import Want from '@ohos.app.ability.Want'; 245import StartOptions from '@ohos.app.ability.StartOptions'; 246import { BusinessError } from '@ohos.base'; 247 248export default class EntryAbility extends UIAbility { 249 250 onForeground() { 251 let want: Want = { 252 bundleName: 'com.example.myapplication', 253 abilityName: 'EntryAbility' 254 }; 255 let options: StartOptions = { 256 windowMode: 0, 257 }; 258 259 try { 260 this.context.startAbility(want, options) 261 .then(() => { 262 // Carry out normal service processing. 263 console.info('startAbility succeed'); 264 }) 265 .catch((err: BusinessError) => { 266 // Process service logic errors. 267 console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`); 268 }); 269 } catch (err) { 270 // Process input parameter errors. 271 let code = (err as BusinessError).code; 272 let message = (err as BusinessError).message; 273 console.error(`startAbility failed, code is ${code}, message is ${message}`); 274 } 275 } 276} 277``` 278 279## UIAbilityContext.startAbilityForResult 280 281startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void 282 283Starts an ability. This API uses an asynchronous callback to return the result when the ability is terminated. The following situations may be possible for a started ability: 284 - Normally, you can call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the ability. The result is returned to the caller. 285 - If an exception occurs, for example, the ability is killed, an error message, in which **resultCode** is **-1**, is returned to the caller. 286 - If different applications call this API to start an ability that uses the singleton mode and then call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the ability, the normal result is returned to the last caller, and an error message, in which **resultCode** is **-1**, is returned to others. 287 288Observe the following when using this API: 289 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 290 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 291 - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 292 293**System capability**: SystemCapability.Ability.AbilityRuntime.Core 294 295**Parameters** 296 297| Name| Type| Mandatory| Description| 298| -------- | -------- | -------- | -------- | 299| want |[Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 300| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Yes| Callback used to return the result.| 301 302**Error codes** 303 304| ID| Error Message| 305| ------- | -------------------------------- | 306| 16000001 | The specified ability does not exist. | 307| 16000002 | Incorrect ability type. | 308| 16000004 | Can not start invisible component. | 309| 16000005 | The specified process does not have the permission. | 310| 16000006 | Cross-user operations are not allowed. | 311| 16000008 | The crowdtesting application expires. | 312| 16000009 | An ability cannot be started or stopped in Wukong mode. | 313| 16000010 | The call with the continuation flag is forbidden. | 314| 16000011 | The context does not exist. | 315| 16000012 | The application is controlled. | 316| 16000013 | The application is controlled by EDM. | 317| 16000050 | Internal error. | 318| 16000053 | The ability is not on the top of the UI. | 319| 16000055 | Installation-free timed out. | 320| 16200001 | The caller has been released. | 321 322For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 323 324**Example** 325 326```ts 327import UIAbility from '@ohos.app.ability.UIAbility'; 328import common from '@ohos.app.ability.common'; 329import Want from '@ohos.app.ability.Want'; 330import { BusinessError } from '@ohos.base'; 331 332export default class EntryAbility extends UIAbility { 333 334 onForeground() { 335 let want: Want = { 336 deviceId: '', 337 bundleName: 'com.example.myapplication', 338 abilityName: 'EntryAbility' 339 }; 340 341 try { 342 this.context.startAbilityForResult(want, (err: BusinessError, result: common.AbilityResult) => { 343 if (err.code) { 344 // Process service logic errors. 345 console.error(`startAbilityForResult failed, code is ${err.code}, message is ${err.message}`); 346 return; 347 } 348 // Carry out normal service processing. 349 console.info('startAbilityForResult succeed'); 350 }); 351 } catch (err) { 352 // Process input parameter errors. 353 let code = (err as BusinessError).code; 354 let message = (err as BusinessError).message; 355 console.error(`startAbilityForResult failed, code is ${code}, message is ${message}`); 356 } 357 } 358} 359``` 360 361## UIAbilityContext.startAbilityForResult 362 363startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void 364 365Starts an ability with the start options specified. This API uses an asynchronous callback to return the result when the ability is terminated. The following situations may be possible for a started ability: 366 - Normally, you can call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the ability. The result is returned to the caller. 367 - If an exception occurs, for example, the ability is killed, an error message, in which **resultCode** is **-1**, is returned to the caller. 368 - If different applications call this API to start an ability that uses the singleton mode and then call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the ability, the normal result is returned to the last caller, and an error message, in which **resultCode** is **-1**, is returned to others. 369 370Observe the following when using this API: 371 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 372 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 373 - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 374 375**System capability**: SystemCapability.Ability.AbilityRuntime.Core 376 377**Parameters** 378 379| Name| Type| Mandatory| Description| 380| -------- | -------- | -------- | -------- | 381| want |[Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 382| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| 383| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Yes| Callback used to return the result.| 384 385**Error codes** 386 387| ID| Error Message| 388| ------- | -------------------------------- | 389| 16000001 | The specified ability does not exist. | 390| 16000002 | Incorrect ability type. | 391| 16000004 | Can not start invisible component. | 392| 16000005 | The specified process does not have the permission. | 393| 16000006 | Cross-user operations are not allowed. | 394| 16000008 | The crowdtesting application expires. | 395| 16000009 | An ability cannot be started or stopped in Wukong mode. | 396| 16000010 | The call with the continuation flag is forbidden. | 397| 16000011 | The context does not exist. | 398| 16000012 | The application is controlled. | 399| 16000013 | The application is controlled by EDM. | 400| 16000050 | Internal error. | 401| 16000053 | The ability is not on the top of the UI. | 402| 16000055 | Installation-free timed out. | 403| 16200001 | The caller has been released. | 404 405For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 406 407**Example** 408 409```ts 410import UIAbility from '@ohos.app.ability.UIAbility'; 411import common from '@ohos.app.ability.common'; 412import Want from '@ohos.app.ability.Want'; 413import StartOptions from '@ohos.app.ability.StartOptions'; 414import { BusinessError } from '@ohos.base'; 415 416export default class EntryAbility extends UIAbility { 417 418 onForeground() { 419 let want: Want = { 420 deviceId: '', 421 bundleName: 'com.example.myapplication', 422 abilityName: 'EntryAbility' 423 }; 424 let options: StartOptions = { 425 windowMode: 0, 426 }; 427 428 try { 429 this.context.startAbilityForResult(want, options, (err: BusinessError, result: common.AbilityResult) => { 430 if (err.code) { 431 // Process service logic errors. 432 console.error(`startAbilityForResult failed, code is ${err.code}, message is ${err.message}`); 433 return; 434 } 435 // Carry out normal service processing. 436 console.info('startAbilityForResult succeed'); 437 }); 438 } catch (err) { 439 // Process input parameter errors. 440 let code = (err as BusinessError).code; 441 let message = (err as BusinessError).message; 442 console.error(`startAbilityForResult failed, code is ${code}, message is ${message}`); 443 } 444 } 445} 446``` 447 448 449## UIAbilityContext.startAbilityForResult 450 451startAbilityForResult(want: Want, options?: StartOptions): Promise<AbilityResult> 452 453Starts an ability. This API uses a promise to return the result when the ability is terminated. The following situations may be possible for a started ability: 454 - Normally, you can call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the ability. The result is returned to the caller. 455 - If an exception occurs, for example, the ability is killed, an error message, in which **resultCode** is **-1**, is returned to the caller. 456 - If different applications call this API to start an ability that uses the singleton mode and then call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the ability, the normal result is returned to the last caller, and an error message, in which **resultCode** is **-1**, is returned to others. 457 458Observe the following when using this API: 459 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 460 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 461 - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 462 463**System capability**: SystemCapability.Ability.AbilityRuntime.Core 464 465**Parameters** 466 467| Name| Type| Mandatory| Description| 468| -------- | -------- | -------- | -------- | 469| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 470| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| 471 472 473**Return value** 474 475| Type| Description| 476| -------- | -------- | 477| Promise<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Promise used to return the result.| 478 479**Error codes** 480 481| ID| Error Message| 482| ------- | -------------------------------- | 483| 16000001 | The specified ability does not exist. | 484| 16000002 | Incorrect ability type. | 485| 16000004 | Can not start invisible component. | 486| 16000005 | The specified process does not have the permission. | 487| 16000006 | Cross-user operations are not allowed. | 488| 16000008 | The crowdtesting application expires. | 489| 16000009 | An ability cannot be started or stopped in Wukong mode. | 490| 16000010 | The call with the continuation flag is forbidden. | 491| 16000011 | The context does not exist. | 492| 16000012 | The application is controlled. | 493| 16000013 | The application is controlled by EDM. | 494| 16000050 | Internal error. | 495| 16000053 | The ability is not on the top of the UI. | 496| 16000055 | Installation-free timed out. | 497| 16200001 | The caller has been released. | 498 499For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 500 501**Example** 502 503```ts 504import UIAbility from '@ohos.app.ability.UIAbility'; 505import common from '@ohos.app.ability.common'; 506import Want from '@ohos.app.ability.Want'; 507import StartOptions from '@ohos.app.ability.StartOptions'; 508import { BusinessError } from '@ohos.base'; 509 510export default class EntryAbility extends UIAbility { 511 512 onForeground() { 513 let want: Want = { 514 bundleName: 'com.example.myapplication', 515 abilityName: 'EntryAbility' 516 }; 517 let options: StartOptions = { 518 windowMode: 0, 519 }; 520 521 try { 522 this.context.startAbilityForResult(want, options) 523 .then((result: common.AbilityResult) => { 524 // Carry out normal service processing. 525 console.info('startAbilityForResult succeed'); 526 }) 527 .catch((err: BusinessError) => { 528 // Process service logic errors. 529 console.error(`startAbilityForResult failed, code is ${err.code}, message is ${err.message}`); 530 }); 531 } catch (err) { 532 // Process input parameter errors. 533 let code = (err as BusinessError).code; 534 let message = (err as BusinessError).message; 535 console.error(`startAbilityForResult failed, code is ${code}, message is ${message}`); 536 } 537 } 538} 539``` 540 541## UIAbilityContext.startAbilityForResultWithAccount 542 543startAbilityForResultWithAccount(want: Want, accountId: number, callback: AsyncCallback\<AbilityResult>): void 544 545Starts an ability with the account ID specified. This API uses an asynchronous callback to return the result when the ability is terminated. 546 547Observe the following when using this API: 548 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 549 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 550 - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 551 552> **NOTE** 553> 554> The **ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS** permission is not required when **accountId** specifies the current user. 555 556**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 557 558**System capability**: SystemCapability.Ability.AbilityRuntime.Core 559 560**System API**: This is a system API and cannot be called by third-party applications. 561 562**Parameters** 563 564| Name| Type| Mandatory| Description| 565| -------- | -------- | -------- | -------- | 566| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 567| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountcount9).| 568| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Yes| Callback used to return the result.| 569 570**Error codes** 571 572| ID| Error Message| 573| ------- | -------------------------------- | 574| 16000001 | The specified ability does not exist. | 575| 16000002 | Incorrect ability type. | 576| 16000004 | Can not start invisible component. | 577| 16000005 | The specified process does not have the permission. | 578| 16000006 | Cross-user operations are not allowed. | 579| 16000008 | The crowdtesting application expires. | 580| 16000009 | An ability cannot be started or stopped in Wukong mode. | 581| 16000010 | The call with the continuation flag is forbidden. | 582| 16000011 | The context does not exist. | 583| 16000012 | The application is controlled. | 584| 16000013 | The application is controlled by EDM. | 585| 16000050 | Internal error. | 586| 16000053 | The ability is not on the top of the UI. | 587| 16000055 | Installation-free timed out. | 588| 16200001 | The caller has been released. | 589 590For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 591 592**Example** 593 594```ts 595import UIAbility from '@ohos.app.ability.UIAbility'; 596import common from '@ohos.app.ability.common'; 597import Want from '@ohos.app.ability.Want'; 598import { BusinessError } from '@ohos.base'; 599 600export default class EntryAbility extends UIAbility { 601 602 onForeground() { 603 604 let want: Want = { 605 deviceId: '', 606 bundleName: 'com.example.myapplication', 607 abilityName: 'EntryAbility' 608 }; 609 let accountId = 100; 610 611 try { 612 this.context.startAbilityForResultWithAccount(want, accountId, (err: BusinessError, result: common.AbilityResult) => { 613 if (err.code) { 614 // Process service logic errors. 615 console.error(`startAbilityForResultWithAccount failed, code is ${err.code}, message is ${err.message}`); 616 return; 617 } 618 // Carry out normal service processing. 619 console.info('startAbilityForResultWithAccount succeed'); 620 }); 621 } catch (err) { 622 // Process input parameter errors. 623 let code = (err as BusinessError).code; 624 let message = (err as BusinessError).message; 625 console.error(`startAbilityForResultWithAccount failed, code is ${code}, message is ${message}`); 626 } 627 } 628} 629``` 630 631 632## UIAbilityContext.startAbilityForResultWithAccount 633 634startAbilityForResultWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback\<void\>): void 635 636Starts an ability with the start options and account ID specified. This API uses an asynchronous callback to return the result when the ability is terminated. 637 638Observe the following when using this API: 639 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 640 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 641 - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 642 643> **NOTE** 644> 645> The **ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS** permission is not required when **accountId** specifies the current user. 646 647**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 648 649**System capability**: SystemCapability.Ability.AbilityRuntime.Core 650 651**System API**: This is a system API and cannot be called by third-party applications. 652 653**Parameters** 654 655| Name| Type| Mandatory| Description| 656| -------- | -------- | -------- | -------- | 657| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 658| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountcount9).| 659| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| 660| callback | AsyncCallback\<void\> | Yes| Callback invoked when the ability is terminated.| 661 662**Error codes** 663 664| ID| Error Message| 665| ------- | -------------------------------- | 666| 16000001 | The specified ability does not exist. | 667| 16000002 | Incorrect ability type. | 668| 16000004 | Can not start invisible component. | 669| 16000005 | The specified process does not have the permission. | 670| 16000006 | Cross-user operations are not allowed. | 671| 16000008 | The crowdtesting application expires. | 672| 16000009 | An ability cannot be started or stopped in Wukong mode. | 673| 16000010 | The call with the continuation flag is forbidden. | 674| 16000011 | The context does not exist. | 675| 16000012 | The application is controlled. | 676| 16000013 | The application is controlled by EDM. | 677| 16000050 | Internal error. | 678| 16000053 | The ability is not on the top of the UI. | 679| 16000055 | Installation-free timed out. | 680| 16200001 | The caller has been released. | 681 682For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 683 684**Example** 685 686```ts 687import UIAbility from '@ohos.app.ability.UIAbility'; 688import Want from '@ohos.app.ability.Want'; 689import StartOptions from '@ohos.app.ability.StartOptions'; 690import { BusinessError } from '@ohos.base'; 691 692export default class EntryAbility extends UIAbility { 693 694 onForeground() { 695 696 let want: Want = { 697 deviceId: '', 698 bundleName: 'com.example.myapplication', 699 abilityName: 'EntryAbility' 700 }; 701 let accountId = 100; 702 let options: StartOptions = { 703 windowMode: 0 704 }; 705 706 try { 707 this.context.startAbilityForResultWithAccount(want, accountId, options, (err: BusinessError) => { 708 if (err.code) { 709 // Process service logic errors. 710 console.error(`startAbilityForResultWithAccount failed, code is ${err.code}, message is ${err.message}`); 711 return; 712 } 713 // Carry out normal service processing. 714 console.info('startAbilityForResultWithAccount succeed'); 715 }); 716 } catch (err) { 717 // Process input parameter errors. 718 let code = (err as BusinessError).code; 719 let message = (err as BusinessError).message; 720 console.error(`startAbilityForResultWithAccount failed, code is ${code}, message is ${message}`); 721 } 722 } 723} 724``` 725 726 727## UIAbilityContext.startAbilityForResultWithAccount 728 729startAbilityForResultWithAccount(want: Want, accountId: number, options?: StartOptions): Promise\<AbilityResult\> 730 731Starts an ability with the account ID specified. This API uses a promise to return the result when the ability is terminated. 732 733Observe the following when using this API: 734 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 735 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 736 - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 737 738> **NOTE** 739> 740> The **ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS** permission is not required when **accountId** specifies the current user. 741 742**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 743 744**System capability**: SystemCapability.Ability.AbilityRuntime.Core 745 746**System API**: This is a system API and cannot be called by third-party applications. 747 748**Parameters** 749 750| Name| Type| Mandatory| Description| 751| -------- | -------- | -------- | -------- | 752| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 753| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountcount9).| 754| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| 755 756**Return value** 757 758| Type| Description| 759| -------- | -------- | 760| Promise<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Promise used to return the ability result when the ability is terminated.| 761 762**Error codes** 763 764| ID| Error Message| 765| ------- | -------------------------------- | 766| 16000001 | The specified ability does not exist. | 767| 16000002 | Incorrect ability type. | 768| 16000004 | Can not start invisible component. | 769| 16000005 | The specified process does not have the permission. | 770| 16000006 | Cross-user operations are not allowed. | 771| 16000008 | The crowdtesting application expires. | 772| 16000009 | An ability cannot be started or stopped in Wukong mode. | 773| 16000010 | The call with the continuation flag is forbidden. | 774| 16000011 | The context does not exist. | 775| 16000012 | The application is controlled. | 776| 16000013 | The application is controlled by EDM. | 777| 16000050 | Internal error. | 778| 16000053 | The ability is not on the top of the UI. | 779| 16000055 | Installation-free timed out. | 780| 16200001 | The caller has been released. | 781 782For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 783 784**Example** 785 786```ts 787import UIAbility from '@ohos.app.ability.UIAbility'; 788import common from '@ohos.app.ability.common'; 789import Want from '@ohos.app.ability.Want'; 790import StartOptions from '@ohos.app.ability.StartOptions'; 791import { BusinessError } from '@ohos.base'; 792 793export default class EntryAbility extends UIAbility { 794 795 onForeground() { 796 let want: Want = { 797 deviceId: '', 798 bundleName: 'com.example.myapplication', 799 abilityName: 'EntryAbility' 800 }; 801 let accountId = 100; 802 let options: StartOptions = { 803 windowMode: 0 804 }; 805 806 try { 807 this.context.startAbilityForResultWithAccount(want, accountId, options) 808 .then((result: common.AbilityResult) => { 809 // Carry out normal service processing. 810 console.info('startAbilityForResultWithAccount succeed'); 811 }) 812 .catch((err: BusinessError) => { 813 // Process service logic errors. 814 console.error(`startAbilityForResultWithAccount failed, code is ${err.code}, message is ${err.message}`); 815 }); 816 } catch (err) { 817 // Process input parameter errors. 818 let code = (err as BusinessError).code; 819 let message = (err as BusinessError).message; 820 console.error(`startAbilityForResultWithAccount failed, code is ${code}, message is ${message}`); 821 } 822 } 823} 824``` 825## UIAbilityContext.startServiceExtensionAbility 826 827startServiceExtensionAbility(want: Want, callback: AsyncCallback\<void>): void 828 829Starts a ServiceExtensionAbility. This API uses an asynchronous callback to return the result. 830 831**System capability**: SystemCapability.Ability.AbilityRuntime.Core 832 833**System API**: This is a system API and cannot be called by third-party applications. 834 835**Parameters** 836 837| Name| Type| Mandatory| Description| 838| -------- | -------- | -------- | -------- | 839| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ServiceExtensionAbility.| 840| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.| 841 842**Error codes** 843 844| ID| Error Message| 845| ------- | -------------------------------- | 846| 16000001 | The specified ability does not exist. | 847| 16000002 | Incorrect ability type. | 848| 16000004 | Can not start invisible component. | 849| 16000005 | The specified process does not have the permission. | 850| 16000006 | Cross-user operations are not allowed. | 851| 16000008 | The crowdtesting application expires. | 852| 16000011 | The context does not exist. | 853| 16000012 | The application is controlled. | 854| 16000013 | The application is controlled by EDM. | 855| 16000050 | Internal error. | 856| 16200001 | The caller has been released. | 857 858For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 859 860**Example** 861 862```ts 863import UIAbility from '@ohos.app.ability.UIAbility'; 864import Want from '@ohos.app.ability.Want'; 865import { BusinessError } from '@ohos.base'; 866 867export default class EntryAbility extends UIAbility { 868 869 onForeground() { 870 let want: Want = { 871 deviceId: '', 872 bundleName: 'com.example.myapplication', 873 abilityName: 'ServiceExtensionAbility' 874 }; 875 876 try { 877 this.context.startServiceExtensionAbility(want) 878 .then(() => { 879 // Carry out normal service processing. 880 console.info('startServiceExtensionAbility succeed'); 881 }) 882 .catch((err: BusinessError) => { 883 // Process service logic errors. 884 console.error(`startServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`); 885 }); 886 } catch (err) { 887 // Process input parameter errors. 888 let code = (err as BusinessError).code; 889 let message = (err as BusinessError).message; 890 console.error(`startServiceExtensionAbility failed, code is ${code}, message is ${message}`); 891 } 892 } 893} 894``` 895 896## UIAbilityContext.startServiceExtensionAbility 897 898startServiceExtensionAbility(want: Want): Promise\<void> 899 900Starts a ServiceExtensionAbility. This API uses a promise to return the result. 901 902**System capability**: SystemCapability.Ability.AbilityRuntime.Core 903 904**System API**: This is a system API and cannot be called by third-party applications. 905 906**Parameters** 907 908| Name| Type| Mandatory| Description| 909| -------- | -------- | -------- | -------- | 910| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ServiceExtensionAbility.| 911 912**Error codes** 913 914| ID| Error Message| 915| ------- | -------------------------------- | 916| 16000001 | The specified ability does not exist. | 917| 16000002 | Incorrect ability type. | 918| 16000004 | Can not start invisible component. | 919| 16000005 | The specified process does not have the permission. | 920| 16000006 | Cross-user operations are not allowed. | 921| 16000008 | The crowdtesting application expires. | 922| 16000011 | The context does not exist. | 923| 16000012 | The application is controlled. | 924| 16000013 | The application is controlled by EDM. | 925| 16000050 | Internal error. | 926| 16200001 | The caller has been released. | 927 928For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 929 930**Example** 931 932```ts 933import UIAbility from '@ohos.app.ability.UIAbility'; 934import Want from '@ohos.app.ability.Want'; 935import { BusinessError } from '@ohos.base'; 936 937export default class EntryAbility extends UIAbility { 938 939 onForeground() { 940 let want: Want = { 941 deviceId: '', 942 bundleName: 'com.example.myapplication', 943 abilityName: 'ServiceExtensionAbility' 944 }; 945 946 try { 947 this.context.startServiceExtensionAbility(want) 948 .then(() => { 949 // Carry out normal service processing. 950 console.info('startServiceExtensionAbility succeed'); 951 }) 952 .catch((err: BusinessError) => { 953 // Process service logic errors. 954 console.error(`startServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`); 955 }); 956 } catch (err) { 957 // Process input parameter errors. 958 let code = (err as BusinessError).code; 959 let message = (err as BusinessError).message; 960 console.error(`startServiceExtensionAbility failed, code is ${code}, message is ${message}`); 961 } 962 } 963} 964``` 965 966## UIAbilityContext.startServiceExtensionAbilityWithAccount 967 968startServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\<void>): void 969 970Starts a ServiceExtensionAbility with the account ID specified. This API uses an asynchronous callback to return the result. 971 972> **NOTE** 973> 974> The **ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS** permission is not required when **accountId** specifies the current user. 975 976**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 977 978**System capability**: SystemCapability.Ability.AbilityRuntime.Core 979 980**System API**: This is a system API and cannot be called by third-party applications. 981 982**Parameters** 983 984| Name| Type| Mandatory| Description| 985| -------- | -------- | -------- | -------- | 986| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ServiceExtensionAbility.| 987| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountcount9).| 988| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.| 989 990**Error codes** 991 992| ID| Error Message| 993| ------- | -------------------------------- | 994| 16000001 | The specified ability does not exist. | 995| 16000002 | Incorrect ability type. | 996| 16000004 | Can not start invisible component. | 997| 16000005 | The specified process does not have the permission. | 998| 16000006 | Cross-user operations are not allowed. | 999| 16000008 | The crowdtesting application expires. | 1000| 16000011 | The context does not exist. | 1001| 16000012 | The application is controlled. | 1002| 16000013 | The application is controlled by EDM. | 1003| 16000050 | Internal error. | 1004| 16200001 | The caller has been released. | 1005 1006For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1007 1008**Example** 1009 1010```ts 1011import UIAbility from '@ohos.app.ability.UIAbility'; 1012import Want from '@ohos.app.ability.Want'; 1013import { BusinessError } from '@ohos.base'; 1014 1015export default class EntryAbility extends UIAbility { 1016 1017 onForeground() { 1018 let want: Want = { 1019 deviceId: '', 1020 bundleName: 'com.example.myapplication', 1021 abilityName: 'ServiceExtensionAbility' 1022 }; 1023 let accountId = 100; 1024 1025 try { 1026 this.context.startServiceExtensionAbilityWithAccount(want, accountId, (err: BusinessError) => { 1027 if (err.code) { 1028 // Process service logic errors. 1029 console.error(`startServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`); 1030 return; 1031 } 1032 // Carry out normal service processing. 1033 console.info('startServiceExtensionAbilityWithAccount succeed'); 1034 }); 1035 } catch (err) { 1036 // Process input parameter errors. 1037 let code = (err as BusinessError).code; 1038 let message = (err as BusinessError).message; 1039 console.error(`startServiceExtensionAbilityWithAccount failed, code is ${code}, message is ${message}`); 1040 } 1041 } 1042} 1043``` 1044 1045## UIAbilityContext.startServiceExtensionAbilityWithAccount 1046 1047startServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise\<void> 1048 1049Starts a ServiceExtensionAbility with the account ID specified. This API uses a promise to return the result. 1050 1051> **NOTE** 1052> 1053> The **ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS** permission is not required when **accountId** specifies the current user. 1054 1055**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 1056 1057**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1058 1059**System API**: This is a system API and cannot be called by third-party applications. 1060 1061**Parameters** 1062 1063| Name| Type| Mandatory| Description| 1064| -------- | -------- | -------- | -------- | 1065| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 1066| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountcount9).| 1067 1068**Error codes** 1069 1070| ID| Error Message| 1071| ------- | -------------------------------- | 1072| 16000001 | The specified ability does not exist. | 1073| 16000002 | Incorrect ability type. | 1074| 16000004 | Can not start invisible component. | 1075| 16000005 | The specified process does not have the permission. | 1076| 16000006 | Cross-user operations are not allowed. | 1077| 16000008 | The crowdtesting application expires. | 1078| 16000011 | The context does not exist. | 1079| 16000012 | The application is controlled. | 1080| 16000013 | The application is controlled by EDM. | 1081| 16000050 | Internal error. | 1082| 16200001 | The caller has been released. | 1083 1084For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1085 1086**Example** 1087 1088```ts 1089import UIAbility from '@ohos.app.ability.UIAbility'; 1090import Want from '@ohos.app.ability.Want'; 1091import { BusinessError } from '@ohos.base'; 1092 1093export default class EntryAbility extends UIAbility { 1094 1095 onForeground() { 1096 let want: Want = { 1097 deviceId: '', 1098 bundleName: 'com.example.myapplication', 1099 abilityName: 'ServiceExtensionAbility' 1100 }; 1101 let accountId = 100; 1102 1103 try { 1104 this.context.startServiceExtensionAbilityWithAccount(want, accountId) 1105 .then(() => { 1106 // Carry out normal service processing. 1107 console.info('startServiceExtensionAbilityWithAccount succeed'); 1108 }) 1109 .catch((err: BusinessError) => { 1110 // Process service logic errors. 1111 console.error(`startServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`); 1112 }); 1113 } catch (err) { 1114 // Process input parameter errors. 1115 let code = (err as BusinessError).code; 1116 let message = (err as BusinessError).message; 1117 console.error(`startServiceExtensionAbilityWithAccount failed, code is ${code}, message is ${message}`); 1118 } 1119 } 1120} 1121``` 1122## UIAbilityContext.stopServiceExtensionAbility 1123 1124stopServiceExtensionAbility(want: Want, callback: AsyncCallback\<void>): void 1125 1126Stops a ServiceExtensionAbility in the same application. This API uses an asynchronous callback to return the result. 1127 1128**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1129 1130**System API**: This is a system API and cannot be called by third-party applications. 1131 1132**Parameters** 1133 1134| Name| Type| Mandatory| Description| 1135| -------- | -------- | -------- | -------- | 1136| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ServiceExtensionAbility.| 1137| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.| 1138 1139**Error codes** 1140 1141| ID| Error Message| 1142| ------- | -------------------------------- | 1143| 16000001 | The specified ability does not exist. | 1144| 16000002 | Incorrect ability type. | 1145| 16000004 | Can not start invisible component. | 1146| 16000005 | The specified process does not have the permission. | 1147| 16000006 | Cross-user operations are not allowed. | 1148| 16000011 | The context does not exist. | 1149| 16000012 | The application is controlled. | 1150| 16000013 | The application is controlled by EDM. | 1151| 16000050 | Internal error. | 1152| 16200001 | The caller has been released. | 1153 1154For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1155 1156**Example** 1157 1158 ```ts 1159import UIAbility from '@ohos.app.ability.UIAbility'; 1160import Want from '@ohos.app.ability.Want'; 1161import { BusinessError } from '@ohos.base'; 1162 1163export default class EntryAbility extends UIAbility { 1164 1165 onForeground() { 1166 let want: Want = { 1167 deviceId: '', 1168 bundleName: 'com.example.myapplication', 1169 abilityName: 'ServiceExtensionAbility' 1170 }; 1171 1172 try { 1173 this.context.stopServiceExtensionAbility(want, (err: BusinessError) => { 1174 if (err.code) { 1175 // Process service logic errors. 1176 console.error(`stopServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`); 1177 return; 1178 } 1179 // Carry out normal service processing. 1180 console.info('stopServiceExtensionAbility succeed'); 1181 }); 1182 } catch (err) { 1183 // Process input parameter errors. 1184 let code = (err as BusinessError).code; 1185 let message = (err as BusinessError).message; 1186 console.error(`stopServiceExtensionAbility failed, code is ${code}, message is ${message}`); 1187 } 1188 } 1189} 1190 ``` 1191 1192## UIAbilityContext.stopServiceExtensionAbility 1193 1194stopServiceExtensionAbility(want: Want): Promise\<void> 1195 1196Stops a ServiceExtensionAbility in the same application. This API uses a promise to return the result. 1197 1198**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1199 1200**System API**: This is a system API and cannot be called by third-party applications. 1201 1202**Parameters** 1203 1204| Name| Type| Mandatory| Description| 1205| -------- | -------- | -------- | -------- | 1206| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ServiceExtensionAbility.| 1207 1208**Error codes** 1209 1210| ID| Error Message| 1211| ------- | -------------------------------- | 1212| 16000001 | The specified ability does not exist. | 1213| 16000002 | Incorrect ability type. | 1214| 16000004 | Can not start invisible component. | 1215| 16000005 | The specified process does not have the permission. | 1216| 16000006 | Cross-user operations are not allowed. | 1217| 16000011 | The context does not exist. | 1218| 16000050 | Internal error. | 1219| 16200001 | The caller has been released. | 1220 1221For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1222 1223**Example** 1224 1225 ```ts 1226import UIAbility from '@ohos.app.ability.UIAbility'; 1227import Want from '@ohos.app.ability.Want'; 1228import { BusinessError } from '@ohos.base'; 1229 1230export default class EntryAbility extends UIAbility { 1231 1232 onForeground() { 1233 let want: Want = { 1234 deviceId: '', 1235 bundleName: 'com.example.myapplication', 1236 abilityName: 'ServiceExtensionAbility' 1237 }; 1238 1239 try { 1240 this.context.stopServiceExtensionAbility(want) 1241 .then(() => { 1242 // Carry out normal service processing. 1243 console.info('stopServiceExtensionAbility succeed'); 1244 }) 1245 .catch((err: BusinessError) => { 1246 // Process service logic errors. 1247 console.error(`stopServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`); 1248 }); 1249 } catch (err) { 1250 // Process input parameter errors. 1251 let code = (err as BusinessError).code; 1252 let message = (err as BusinessError).message; 1253 console.error(`stopServiceExtensionAbility failed, code is ${code}, message is ${message}`); 1254 } 1255 } 1256} 1257 ``` 1258 1259## UIAbilityContext.stopServiceExtensionAbilityWithAccount 1260 1261stopServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\<void>): void 1262 1263Stops a ServiceExtensionAbility with the account ID specified in the same application. This API uses an asynchronous callback to return the result. 1264 1265> **NOTE** 1266> 1267> The **ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS** permission is not required when **accountId** specifies the current user. 1268 1269**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 1270 1271**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1272 1273**System API**: This is a system API and cannot be called by third-party applications. 1274 1275**Parameters** 1276 1277| Name| Type| Mandatory| Description| 1278| -------- | -------- | -------- | -------- | 1279| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ServiceExtensionAbility.| 1280| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountcount9).| 1281| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.| 1282 1283**Error codes** 1284 1285| ID| Error Message| 1286| ------- | -------------------------------- | 1287| 16000001 | The specified ability does not exist. | 1288| 16000002 | Incorrect ability type. | 1289| 16000004 | Can not start invisible component. | 1290| 16000005 | The specified process does not have the permission. | 1291| 16000006 | Cross-user operations are not allowed. | 1292| 16000011 | The context does not exist. | 1293| 16000050 | Internal error. | 1294| 16200001 | The caller has been released. | 1295 1296For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1297 1298**Example** 1299 1300```ts 1301import UIAbility from '@ohos.app.ability.UIAbility'; 1302import Want from '@ohos.app.ability.Want'; 1303import { BusinessError } from '@ohos.base'; 1304 1305export default class EntryAbility extends UIAbility { 1306 1307 onForeground() { 1308 let want: Want = { 1309 deviceId: '', 1310 bundleName: 'com.example.myapplication', 1311 abilityName: 'ServiceExtensionAbility' 1312 }; 1313 let accountId = 100; 1314 1315 try { 1316 this.context.stopServiceExtensionAbilityWithAccount(want, accountId, (err: BusinessError) => { 1317 if (err.code) { 1318 // Process service logic errors. 1319 console.error(`stopServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`); 1320 return; 1321 } 1322 // Carry out normal service processing. 1323 console.info('stopServiceExtensionAbilityWithAccount succeed'); 1324 }); 1325 } catch (err) { 1326 // Process input parameter errors. 1327 let code = (err as BusinessError).code; 1328 let message = (err as BusinessError).message; 1329 console.error(`stopServiceExtensionAbilityWithAccount failed, code is ${code}, message is ${message}`); 1330 } 1331 } 1332} 1333``` 1334 1335## UIAbilityContext.stopServiceExtensionAbilityWithAccount 1336 1337stopServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise\<void> 1338 1339Stops a ServiceExtensionAbility with the account ID specified in the same application. This API uses a promise to return the result. 1340 1341> **NOTE** 1342> 1343> The **ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS** permission is not required when **accountId** specifies the current user. 1344 1345**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 1346 1347**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1348 1349**System API**: This is a system API and cannot be called by third-party applications. 1350 1351**Parameters** 1352 1353| Name| Type| Mandatory| Description| 1354| -------- | -------- | -------- | -------- | 1355| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ServiceExtensionAbility.| 1356| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountcount9).| 1357 1358**Error codes** 1359 1360| ID| Error Message| 1361| ------- | -------------------------------- | 1362| 16000001 | The specified ability does not exist. | 1363| 16000002 | Incorrect ability type. | 1364| 16000004 | Can not start invisible component. | 1365| 16000005 | The specified process does not have the permission. | 1366| 16000006 | Cross-user operations are not allowed. | 1367| 16000011 | The context does not exist. | 1368| 16000050 | Internal error. | 1369| 16200001 | The caller has been released. | 1370 1371For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1372 1373**Example** 1374 1375```ts 1376import UIAbility from '@ohos.app.ability.UIAbility'; 1377import Want from '@ohos.app.ability.Want'; 1378import { BusinessError } from '@ohos.base'; 1379 1380export default class EntryAbility extends UIAbility { 1381 1382 onForeground() { 1383 let want: Want = { 1384 deviceId: '', 1385 bundleName: 'com.example.myapplication', 1386 abilityName: 'ServiceExtensionAbility' 1387 }; 1388 let accountId = 100; 1389 1390 try { 1391 this.context.stopServiceExtensionAbilityWithAccount(want, accountId) 1392 .then(() => { 1393 // Carry out normal service processing. 1394 console.info('stopServiceExtensionAbilityWithAccount succeed'); 1395 }) 1396 .catch((err: BusinessError) => { 1397 // Process service logic errors. 1398 console.error(`stopServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`); 1399 }); 1400 } catch (err) { 1401 // Process input parameter errors. 1402 let code = (err as BusinessError).code; 1403 let message = (err as BusinessError).message; 1404 console.error(`stopServiceExtensionAbilityWithAccount failed, code is ${code}, message is ${message}`); 1405 } 1406 } 1407} 1408``` 1409 1410## UIAbilityContext.terminateSelf 1411 1412terminateSelf(callback: AsyncCallback<void>): void 1413 1414Terminates this ability. This API uses an asynchronous callback to return the result. 1415 1416**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1417 1418**Parameters** 1419 1420| Name| Type| Mandatory| Description| 1421| -------- | -------- | -------- | -------- | 1422| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 1423 1424**Error codes** 1425 1426| ID| Error Message| 1427| ------- | -------------------------------- | 1428| 16000001 | The specified ability does not exist. | 1429| 16000004 | Can not start invisible component. | 1430| 16000005 | The specified process does not have the permission. | 1431| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1432| 16000011 | The context does not exist. | 1433| 16000050 | Internal error. | 1434 1435For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1436 1437**Example** 1438 1439```ts 1440import UIAbility from '@ohos.app.ability.UIAbility'; 1441import { BusinessError } from '@ohos.base'; 1442 1443export default class EntryAbility extends UIAbility { 1444 1445 onForeground() { 1446 try { 1447 this.context.terminateSelf((err: BusinessError) => { 1448 if (err.code) { 1449 // Process service logic errors. 1450 console.error(`terminateSelf failed, code is ${err.code}, message is ${err.message}`); 1451 return; 1452 } 1453 // Carry out normal service processing. 1454 console.info('terminateSelf succeed'); 1455 }); 1456 } catch (err) { 1457 // Capture the synchronization parameter error. 1458 let code = (err as BusinessError).code; 1459 let message = (err as BusinessError).message; 1460 console.error(`terminateSelf failed, code is ${code}, message is ${message}`); 1461 } 1462 } 1463} 1464``` 1465 1466 1467## UIAbilityContext.terminateSelf 1468 1469terminateSelf(): Promise<void> 1470 1471Terminates this ability. This API uses a promise to return the result. 1472 1473**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1474 1475**Return value** 1476 1477| Type| Description| 1478| -------- | -------- | 1479| Promise<void> | Promise used to return the result.| 1480 1481**Error codes** 1482 1483| ID| Error Message| 1484| ------- | -------------------------------- | 1485| 16000001 | The specified ability does not exist. | 1486| 16000004 | Can not start invisible component. | 1487| 16000005 | The specified process does not have the permission. | 1488| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1489| 16000011 | The context does not exist. | 1490| 16000050 | Internal error. | 1491 1492For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1493 1494**Example** 1495 1496```ts 1497import UIAbility from '@ohos.app.ability.UIAbility'; 1498import { BusinessError } from '@ohos.base'; 1499 1500export default class EntryAbility extends UIAbility { 1501 1502 onForeground() { 1503 try { 1504 this.context.terminateSelf() 1505 .then(() => { 1506 // Carry out normal service processing. 1507 console.info('terminateSelf succeed'); 1508 }) 1509 .catch((err: BusinessError) => { 1510 // Process service logic errors. 1511 console.error(`terminateSelf failed, code is ${err.code}, message is ${err.message}`); 1512 }); 1513 } catch (err) { 1514 // Capture the synchronization parameter error. 1515 let code = (err as BusinessError).code; 1516 let message = (err as BusinessError).message; 1517 console.error(`terminateSelf failed, code is ${code}, message is ${message}`); 1518 } 1519 } 1520} 1521``` 1522 1523 1524## UIAbilityContext.terminateSelfWithResult 1525 1526terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void 1527 1528Terminates this ability. If the ability is started by calling [startAbilityForResult](#uiabilitycontextstartabilityforresult), the result is returned to the caller in the form of an asynchronous callback when **terminateSelfWithResult** is called. Otherwise, no result is returned to the caller when **terminateSelfWithResult** is called. 1529 1530**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1531 1532**Parameters** 1533 1534| Name| Type| Mandatory| Description| 1535| -------- | -------- | -------- | -------- | 1536| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | Yes| Information returned to the caller.| 1537| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 1538 1539**Error codes** 1540 1541| ID| Error Message| 1542| ------- | -------------------------------- | 1543| 16000001 | The specified ability does not exist. | 1544| 16000004 | Can not start invisible component. | 1545| 16000005 | The specified process does not have the permission. | 1546| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1547| 16000011 | The context does not exist. | 1548| 16000050 | Internal error. | 1549 1550For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1551 1552**Example** 1553 1554```ts 1555import UIAbility from '@ohos.app.ability.UIAbility'; 1556import common from '@ohos.app.ability.common'; 1557import Want from '@ohos.app.ability.Want'; 1558import { BusinessError } from '@ohos.base'; 1559 1560export default class EntryAbility extends UIAbility { 1561 1562 onForeground() { 1563 let want: Want = { 1564 bundleName: 'com.example.myapplication', 1565 abilityName: 'EntryAbility' 1566 }; 1567 let resultCode = 100; 1568 // AbilityResult information returned to the caller. 1569 let abilityResult: common.AbilityResult = { 1570 want, 1571 resultCode 1572 }; 1573 1574 try { 1575 this.context.terminateSelfWithResult(abilityResult, (err: BusinessError) => { 1576 if (err.code) { 1577 // Process service logic errors. 1578 console.error(`terminateSelfWithResult failed, code is ${err.code}, message is ${err.message}`); 1579 return; 1580 } 1581 // Carry out normal service processing. 1582 console.info('terminateSelfWithResult succeed'); 1583 }); 1584 } catch (err) { 1585 // Process input parameter errors. 1586 let code = (err as BusinessError).code; 1587 let message = (err as BusinessError).message; 1588 console.error(`terminateSelfWithResult failed, code is ${code}, message is ${message}`); 1589 } 1590 } 1591} 1592``` 1593 1594 1595## UIAbilityContext.terminateSelfWithResult 1596 1597terminateSelfWithResult(parameter: AbilityResult): Promise<void> 1598 1599Terminates this ability. If the ability is started by calling [startAbilityForResult](#uiabilitycontextstartabilityforresult), the result is returned to the caller in the form of a promise when **terminateSelfWithResult** is called. Otherwise, no result is returned to the caller when **terminateSelfWithResult** is called. 1600 1601**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1602 1603**Parameters** 1604 1605| Name| Type| Mandatory| Description| 1606| -------- | -------- | -------- | -------- | 1607| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | Yes| Information returned to the caller.| 1608 1609**Return value** 1610 1611| Type| Description| 1612| -------- | -------- | 1613| Promise<void> | Promise used to return the result.| 1614 1615**Error codes** 1616 1617| ID| Error Message| 1618| ------- | -------------------------------- | 1619| 16000001 | The specified ability does not exist. | 1620| 16000004 | Can not start invisible component. | 1621| 16000005 | The specified process does not have the permission. | 1622| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1623| 16000011 | The context does not exist. | 1624| 16000050 | Internal error. | 1625 1626For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1627 1628**Example** 1629 1630```ts 1631import UIAbility from '@ohos.app.ability.UIAbility'; 1632import common from '@ohos.app.ability.common'; 1633import Want from '@ohos.app.ability.Want'; 1634import { BusinessError } from '@ohos.base'; 1635 1636export default class EntryAbility extends UIAbility { 1637 1638 onForeground() { 1639 let want: Want = { 1640 bundleName: 'com.example.myapplication', 1641 abilityName: 'EntryAbility' 1642 }; 1643 let resultCode = 100; 1644 // AbilityResult information returned to the caller. 1645 let abilityResult: common.AbilityResult = { 1646 want, 1647 resultCode 1648 }; 1649 1650 try { 1651 this.context.terminateSelfWithResult(abilityResult) 1652 .then(() => { 1653 // Carry out normal service processing. 1654 console.info('terminateSelfWithResult succeed'); 1655 }) 1656 .catch((err: BusinessError) => { 1657 // Process service logic errors. 1658 console.error(`terminateSelfWithResult failed, code is ${err.code}, message is ${err.message}`); 1659 }); 1660 } catch (err) { 1661 // Process input parameter errors. 1662 let code = (err as BusinessError).code; 1663 let message = (err as BusinessError).message; 1664 console.error(`terminateSelfWithResult failed, code is ${code}, message is ${message}`); 1665 } 1666 } 1667} 1668``` 1669 1670## UIAbilityContext.connectServiceExtensionAbility 1671 1672connectServiceExtensionAbility(want: Want, options: ConnectOptions): number 1673 1674Connects this ability to an ability that uses the **AbilityInfo.AbilityType.SERVICE** template. 1675 1676**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1677 1678**Parameters** 1679 1680| Name| Type| Mandatory| Description| 1681| -------- | -------- | -------- | -------- | 1682| want | [Want](js-apis-app-ability-want.md) | Yes| Want information for connecting to the ServiceExtensionAbility.| 1683| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | Yes| Instance of the callback function after the connection to the ServiceExtensionAbility is set up.| 1684 1685**Return value** 1686 1687| Type| Description| 1688| -------- | -------- | 1689| number | Result code of the ability connection.| 1690 1691**Error codes** 1692 1693| ID| Error Message| 1694| ------- | -------------------------------- | 1695| 16000001 | The specified ability does not exist. | 1696| 16000002 | Incorrect ability type. | 1697| 16000004 | Can not start invisible component. | 1698| 16000005 | The specified process does not have the permission. | 1699| 16000006 | Cross-user operations are not allowed. | 1700| 16000008 | The crowdtesting application expires. | 1701| 16000053 | The ability is not on the top of the UI. | 1702| 16000055 | Installation-free timed out. | 1703| 16000011 | The context does not exist. | 1704| 16000050 | Internal error. | 1705 1706For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1707 1708**Example** 1709 1710```ts 1711import UIAbility from '@ohos.app.ability.UIAbility'; 1712import common from '@ohos.app.ability.common'; 1713import Want from '@ohos.app.ability.Want'; 1714import { BusinessError } from '@ohos.base'; 1715import rpc from '@ohos.rpc'; 1716 1717export default class EntryAbility extends UIAbility { 1718 1719 onForeground() { 1720 let want: Want = { 1721 deviceId: '', 1722 bundleName: 'com.example.myapplication', 1723 abilityName: 'ServiceExtensionAbility' 1724 }; 1725 let commRemote: rpc.IRemoteObject; 1726 let options: common.ConnectOptions = { 1727 onConnect(elementName, remote) { 1728 commRemote = remote; 1729 console.info('onConnect...') 1730 }, 1731 onDisconnect(elementName) { 1732 console.info('onDisconnect...') 1733 }, 1734 onFailed(code) { 1735 console.info('onFailed...') 1736 } 1737 }; 1738 let connection: number; 1739 try { 1740 connection = this.context.connectServiceExtensionAbility(want, options); 1741 } catch (err) { 1742 // Process input parameter errors. 1743 let code = (err as BusinessError).code; 1744 let message = (err as BusinessError).message; 1745 console.error(`connectServiceExtensionAbility failed, code is ${code}, message is ${message}`); 1746 } 1747 } 1748} 1749``` 1750 1751 1752## UIAbilityContext.connectServiceExtensionAbilityWithAccount 1753 1754connectServiceExtensionAbilityWithAccount(want: Want, accountId: number, options: ConnectOptions): number 1755 1756Connects this ability to an ability that uses the **AbilityInfo.AbilityType.SERVICE** template, with the account ID specified. 1757 1758> **NOTE** 1759> 1760> The **ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS** permission is not required when **accountId** specifies the current user. 1761 1762**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 1763 1764**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1765 1766**System API**: This is a system API and cannot be called by third-party applications. 1767 1768**Parameters** 1769 1770| Name| Type| Mandatory| Description| 1771| -------- | -------- | -------- | -------- | 1772| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 1773| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountcount9).| 1774| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | Yes| Instance of the callback function after the connection to the ServiceExtensionAbility is set up.| 1775 1776**Return value** 1777 1778| Type| Description| 1779| -------- | -------- | 1780| number | Result code of the ability connection.| 1781 1782**Error codes** 1783 1784| ID| Error Message| 1785| ------- | -------------------------------- | 1786| 16000001 | The specified ability does not exist. | 1787| 16000002 | Incorrect ability type. | 1788| 16000004 | Can not start invisible component. | 1789| 16000005 | The specified process does not have the permission. | 1790| 16000006 | Cross-user operations are not allowed. | 1791| 16000008 | The crowdtesting application expires. | 1792| 16000053 | The ability is not on the top of the UI. | 1793| 16000055 | Installation-free timed out. | 1794| 16000011 | The context does not exist. | 1795| 16000050 | Internal error. | 1796 1797For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1798 1799**Example** 1800 1801```ts 1802import UIAbility from '@ohos.app.ability.UIAbility'; 1803import common from '@ohos.app.ability.common'; 1804import Want from '@ohos.app.ability.Want'; 1805import { BusinessError } from '@ohos.base'; 1806import rpc from '@ohos.rpc'; 1807 1808export default class EntryAbility extends UIAbility { 1809 1810 onForeground() { 1811 let want: Want = { 1812 deviceId: '', 1813 bundleName: 'com.example.myapplication', 1814 abilityName: 'ServiceExtensionAbility' 1815 }; 1816 let accountId = 100; 1817 let commRemote: rpc.IRemoteObject; 1818 let options: common.ConnectOptions = { 1819 onConnect(elementName, remote) { 1820 commRemote = remote; 1821 console.info('onConnect...') 1822 }, 1823 onDisconnect(elementName) { 1824 console.info('onDisconnect...') 1825 }, 1826 onFailed(code) { 1827 console.info('onFailed...') 1828 } 1829 }; 1830 let connection: number; 1831 try { 1832 connection = this.context.connectServiceExtensionAbilityWithAccount(want, accountId, options); 1833 } catch (err) { 1834 // Process input parameter errors. 1835 let code = (err as BusinessError).code; 1836 let message = (err as BusinessError).message; 1837 console.error(`connectServiceExtensionAbility failed, code is ${code}, message is ${message}`); 1838 } 1839 } 1840} 1841``` 1842 1843## UIAbilityContext.disconnectServiceExtensionAbility 1844 1845disconnectServiceExtensionAbility(connection: number): Promise\<void> 1846 1847Disconnects this ability from a ServiceExtensionAbility and after the successful disconnection, sets the remote object returned upon the connection to void. This API uses a promise to return the result. 1848 1849**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1850 1851**Parameters** 1852 1853| Name| Type| Mandatory| Description| 1854| -------- | -------- | -------- | -------- | 1855| connection | number | Yes| Digital code of the connected ServiceExtensionAbility, that is, connectionId returned by **connectServiceExtensionAbility**.| 1856 1857**Return value** 1858 1859| Type| Description| 1860| -------- | -------- | 1861| Promise\<void> | Promise used to return the result.| 1862 1863**Error codes** 1864 1865| ID| Error Message| 1866| ------- | -------------------------------- | 1867| 16000011 | The context does not exist. | 1868| 16000050 | Internal error. | 1869 1870For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1871 1872**Example** 1873 1874```ts 1875import UIAbility from '@ohos.app.ability.UIAbility'; 1876import { BusinessError } from '@ohos.base'; 1877import rpc from '@ohos.rpc'; 1878 1879export default class EntryAbility extends UIAbility { 1880 1881 onForeground() { 1882 // connection is the return value of connectServiceExtensionAbility. 1883 let connection = 1; 1884 let commRemote: rpc.IRemoteObject | null; 1885 1886 try { 1887 this.context.disconnectServiceExtensionAbility(connection).then(() => { 1888 commRemote = null; 1889 // Carry out normal service processing. 1890 console.info('disconnectServiceExtensionAbility succeed'); 1891 }).catch((err: BusinessError) => { 1892 // Process service logic errors. 1893 console.error(`disconnectServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`); 1894 }) 1895 } catch (err) { 1896 commRemote = null; 1897 // Process input parameter errors. 1898 let code = (err as BusinessError).code; 1899 let message = (err as BusinessError).message; 1900 console.error(`disconnectServiceExtensionAbility failed, code is ${code}, message is ${message}`); 1901 } 1902 } 1903} 1904``` 1905 1906## UIAbilityContext.disconnectServiceExtensionAbility 1907 1908disconnectServiceExtensionAbility(connection: number, callback: AsyncCallback\<void>): void 1909 1910Disconnects this ability from a ServiceExtensionAbility and after the successful disconnection, sets the remote object returned upon the connection to void. This API uses an asynchronous callback to return the result. 1911 1912**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1913 1914**Parameters** 1915 1916| Name| Type| Mandatory| Description| 1917| -------- | -------- | -------- | -------- | 1918| connection | number | Yes| Digital code of the connected ServiceExtensionAbility, that is, connectionId returned by **connectServiceExtensionAbility**.| 1919| callback | AsyncCallback\<void> | Yes| Callback used to return the result.| 1920 1921**Error codes** 1922 1923| ID| Error Message| 1924| ------- | -------------------------------- | 1925| 16000011 | The context does not exist. | 1926| 16000050 | Internal error. | 1927 1928For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1929 1930**Example** 1931 1932```ts 1933import UIAbility from '@ohos.app.ability.UIAbility'; 1934import { BusinessError } from '@ohos.base'; 1935import rpc from '@ohos.rpc'; 1936 1937export default class EntryAbility extends UIAbility { 1938 1939 onForeground() { 1940 // connection is the return value of connectServiceExtensionAbility. 1941 let connection = 1; 1942 let commRemote: rpc.IRemoteObject | null; 1943 1944 try { 1945 this.context.disconnectServiceExtensionAbility(connection, (err: BusinessError) => { 1946 commRemote = null; 1947 if (err.code) { 1948 // Process service logic errors. 1949 console.error(`disconnectServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`); 1950 return; 1951 } 1952 // Carry out normal service processing. 1953 console.info('disconnectServiceExtensionAbility succeed'); 1954 }); 1955 } catch (err) { 1956 commRemote = null; 1957 // Process input parameter errors. 1958 let code = (err as BusinessError).code; 1959 let message = (err as BusinessError).message; 1960 console.error(`disconnectServiceExtensionAbility failed, code is ${code}, message is ${message}`); 1961 } 1962 } 1963} 1964``` 1965 1966## UIAbilityContext.startAbilityByCall 1967 1968startAbilityByCall(want: Want): Promise<Caller> 1969 1970Starts an ability in the foreground or background in the cross-device scenario and obtains the caller object for communicating with the ability. 1971 1972Observe the following when using this API: 1973 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 1974 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 1975 1976**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 1977 1978> **NOTE** 1979> 1980> In versions earlier than API version 11, the permission **ohos.permission.ABILITY_BACKGROUND_COMMUNICATION** is required. Since API version 11, only the permission **ohos.permission.DISTRIBUTED_DATASYNC** is required. 1981 1982**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1983 1984**Parameters** 1985 1986| Name| Type| Mandatory| Description| 1987| -------- | -------- | -------- | -------- | 1988| want | [Want](js-apis-app-ability-want.md) | Yes| Information about the ability to start, including **abilityName**, **moduleName**, **bundleName**, **deviceId** (optional), and **parameters** (optional). If **deviceId** is left blank or null, the local ability is started. If **parameters** is left blank or null, the ability is started in the background.| 1989 1990**Return value** 1991 1992| Type| Description| 1993| -------- | -------- | 1994| Promise<Caller> | Promise used to return the caller object to communicate with.| 1995 1996**Error codes** 1997 1998| ID| Error Message| 1999| ------- | -------------------------------- | 2000| 16000001 | The specified ability does not exist. | 2001| 16000002 | Incorrect ability type. | 2002| 16000004 | Can not start invisible component. | 2003| 16000005 | The specified process does not have the permission. | 2004| 16000006 | Cross-user operations are not allowed. | 2005| 16000008 | The crowdtesting application expires. | 2006| 16000011 | The context does not exist. | 2007| 16000012 | The application is controlled. | 2008| 16000013 | The application is controlled by EDM. | 2009| 16000050 | Internal error. | 2010| 16200001 | The caller has been released. | 2011 2012For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 2013 2014**Example** 2015 2016Start an ability in the background. 2017 2018```ts 2019import UIAbility from '@ohos.app.ability.UIAbility'; 2020import { Caller } from '@ohos.app.ability.UIAbility'; 2021import Want from '@ohos.app.ability.Want'; 2022import { BusinessError } from '@ohos.base'; 2023 2024export default class EntryAbility extends UIAbility { 2025 2026 onForeground() { 2027 let caller: Caller; 2028 2029 // Start an ability in the background by not passing parameters. 2030 let wantBackground: Want = { 2031 bundleName: 'com.example.myapplication', 2032 moduleName: 'entry', 2033 abilityName: 'EntryAbility', 2034 deviceId: '' 2035 }; 2036 2037 try { 2038 this.context.startAbilityByCall(wantBackground) 2039 .then((obj: Caller) => { 2040 // Carry out normal service processing. 2041 caller = obj; 2042 console.info('startAbilityByCall succeed'); 2043 }).catch((err: BusinessError) => { 2044 // Process service logic errors. 2045 console.error(`startAbilityByCall failed, code is ${err.code}, message is ${err.message}`); 2046 }); 2047 } catch (err) { 2048 // Process input parameter errors. 2049 let code = (err as BusinessError).code; 2050 let message = (err as BusinessError).message; 2051 console.error(`startAbilityByCall failed, code is ${code}, message is ${message}`); 2052 } 2053 } 2054} 2055``` 2056 2057Start an ability in the foreground. 2058 2059```ts 2060import UIAbility from '@ohos.app.ability.UIAbility'; 2061import { Caller } from '@ohos.app.ability.UIAbility'; 2062import Want from '@ohos.app.ability.Want'; 2063import { BusinessError } from '@ohos.base'; 2064 2065export default class EntryAbility extends UIAbility { 2066 2067 onForeground() { 2068 let caller: Caller; 2069 2070 // Start an ability in the foreground with 'ohos.aafwk.param.callAbilityToForeground' in parameters set to true. 2071 let wantForeground: Want = { 2072 bundleName: 'com.example.myapplication', 2073 moduleName: 'entry', 2074 abilityName: 'EntryAbility', 2075 deviceId: '', 2076 parameters: { 2077 'ohos.aafwk.param.callAbilityToForeground': true 2078 } 2079 }; 2080 2081 try { 2082 this.context.startAbilityByCall(wantForeground) 2083 .then((obj: Caller) => { 2084 // Carry out normal service processing. 2085 caller = obj; 2086 console.info('startAbilityByCall succeed'); 2087 }).catch((err: BusinessError) => { 2088 // Process service logic errors. 2089 console.error(`startAbilityByCall failed, code is ${err.code}, message is ${err.message}`); 2090 }); 2091 } catch (err) { 2092 // Process input parameter errors. 2093 let code = (err as BusinessError).code; 2094 let message = (err as BusinessError).message; 2095 console.error(`startAbilityByCall failed, code is ${code}, message is ${message}`); 2096 } 2097 } 2098} 2099``` 2100 2101## UIAbilityContext.startAbilityWithAccount 2102 2103startAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\<void\>): void 2104 2105Starts an ability with the account ID specified. This API uses an asynchronous callback to return the result. 2106 2107Observe the following when using this API: 2108 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 2109 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 2110 - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 2111 2112> **NOTE** 2113> 2114> The **ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS** permission is not required when **accountId** specifies the current user. 2115 2116**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 2117 2118**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2119 2120**System API**: This is a system API and cannot be called by third-party applications. 2121 2122**Parameters** 2123 2124| Name| Type| Mandatory| Description| 2125| -------- | -------- | -------- | -------- | 2126| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 2127| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountcount9).| 2128| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.| 2129 2130**Error codes** 2131 2132| ID| Error Message| 2133| ------- | -------------------------------- | 2134| 16000001 | The specified ability does not exist. | 2135| 16000002 | Incorrect ability type. | 2136| 16000004 | Can not start invisible component. | 2137| 16000005 | The specified process does not have the permission. | 2138| 16000006 | Cross-user operations are not allowed. | 2139| 16000008 | The crowdtesting application expires. | 2140| 16000009 | An ability cannot be started or stopped in Wukong mode. | 2141| 16000010 | The call with the continuation flag is forbidden. | 2142| 16000011 | The context does not exist. | 2143| 16000012 | The application is controlled. | 2144| 16000013 | The application is controlled by EDM. | 2145| 16000050 | Internal error. | 2146| 16000053 | The ability is not on the top of the UI. | 2147| 16000055 | Installation-free timed out. | 2148| 16200001 | The caller has been released. | 2149 2150For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 2151 2152**Example** 2153 2154```ts 2155import UIAbility from '@ohos.app.ability.UIAbility'; 2156import Want from '@ohos.app.ability.Want'; 2157import { BusinessError } from '@ohos.base'; 2158 2159export default class EntryAbility extends UIAbility { 2160 2161 onForeground() { 2162 let want: Want = { 2163 deviceId: '', 2164 bundleName: 'com.example.myapplication', 2165 abilityName: 'EntryAbility' 2166 }; 2167 let accountId = 100; 2168 2169 try { 2170 this.context.startAbilityWithAccount(want, accountId, (err: BusinessError) => { 2171 if (err.code) { 2172 // Process service logic errors. 2173 console.error(`startAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`); 2174 return; 2175 } 2176 // Carry out normal service processing. 2177 console.info('startAbilityWithAccount succeed'); 2178 }); 2179 } catch (err) { 2180 // Process input parameter errors. 2181 let code = (err as BusinessError).code; 2182 let message = (err as BusinessError).message; 2183 console.error(`startAbilityWithAccount failed, code is ${code}, message is ${message}`); 2184 } 2185 } 2186} 2187``` 2188 2189 2190## UIAbilityContext.startAbilityWithAccount 2191 2192startAbilityWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback\<void\>): void 2193 2194Starts an ability with the account ID and start options specified. This API uses an asynchronous callback to return the result. 2195 2196Observe the following when using this API: 2197 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 2198 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 2199 - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 2200 2201> **NOTE** 2202> 2203> The **ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS** permission is not required when **accountId** specifies the current user. 2204 2205**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 2206 2207**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2208 2209**System API**: This is a system API and cannot be called by third-party applications. 2210 2211**Parameters** 2212 2213| Name| Type| Mandatory| Description| 2214| -------- | -------- | -------- | -------- | 2215| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 2216| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountcount9).| 2217| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| 2218| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.| 2219 2220**Error codes** 2221 2222| ID| Error Message| 2223| ------- | -------------------------------- | 2224| 16000001 | The specified ability does not exist. | 2225| 16000002 | Incorrect ability type. | 2226| 16000004 | Can not start invisible component. | 2227| 16000005 | The specified process does not have the permission. | 2228| 16000006 | Cross-user operations are not allowed. | 2229| 16000008 | The crowdtesting application expires. | 2230| 16000009 | An ability cannot be started or stopped in Wukong mode. | 2231| 16000010 | The call with the continuation flag is forbidden. | 2232| 16000011 | The context does not exist. | 2233| 16000012 | The application is controlled. | 2234| 16000013 | The application is controlled by EDM. | 2235| 16000050 | Internal error. | 2236| 16000053 | The ability is not on the top of the UI. | 2237| 16000055 | Installation-free timed out. | 2238| 16200001 | The caller has been released. | 2239 2240For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 2241 2242**Example** 2243 2244```ts 2245import UIAbility from '@ohos.app.ability.UIAbility'; 2246import Want from '@ohos.app.ability.Want'; 2247import StartOptions from '@ohos.app.ability.StartOptions'; 2248import { BusinessError } from '@ohos.base'; 2249 2250export default class EntryAbility extends UIAbility { 2251 2252 onForeground() { 2253 let want: Want = { 2254 deviceId: '', 2255 bundleName: 'com.example.myapplication', 2256 abilityName: 'EntryAbility' 2257 }; 2258 let accountId = 100; 2259 let options: StartOptions = { 2260 windowMode: 0 2261 }; 2262 2263 try { 2264 this.context.startAbilityWithAccount(want, accountId, options, (err: BusinessError) => { 2265 if (err.code) { 2266 // Process service logic errors. 2267 console.error(`startAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`); 2268 return; 2269 } 2270 // Carry out normal service processing. 2271 console.info('startAbilityWithAccount succeed'); 2272 }); 2273 } catch (err) { 2274 // Process input parameter errors. 2275 let code = (err as BusinessError).code; 2276 let message = (err as BusinessError).message; 2277 console.error(`startAbilityWithAccount failed, code is ${code}, message is ${message}`); 2278 } 2279 } 2280} 2281``` 2282 2283 2284## UIAbilityContext.startAbilityWithAccount 2285 2286startAbilityWithAccount(want: Want, accountId: number, options?: StartOptions): Promise\<void\> 2287 2288Starts an ability with the account ID specified. This API uses a promise to return the result. 2289 2290Observe the following when using this API: 2291 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 2292 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 2293 - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 2294 2295> **NOTE** 2296> 2297> The **ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS** permission is not required when **accountId** specifies the current user. 2298 2299**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 2300 2301**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2302 2303**System API**: This is a system API and cannot be called by third-party applications. 2304 2305**Parameters** 2306 2307| Name| Type| Mandatory| Description| 2308| -------- | -------- | -------- | -------- | 2309| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 2310| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountcount9).| 2311| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| 2312 2313**Error codes** 2314 2315| ID| Error Message| 2316| ------- | -------------------------------- | 2317| 16000001 | The specified ability does not exist. | 2318| 16000002 | Incorrect ability type. | 2319| 16000004 | Can not start invisible component. | 2320| 16000005 | The specified process does not have the permission. | 2321| 16000006 | Cross-user operations are not allowed. | 2322| 16000008 | The crowdtesting application expires. | 2323| 16000009 | An ability cannot be started or stopped in Wukong mode. | 2324| 16000010 | The call with the continuation flag is forbidden. | 2325| 16000011 | The context does not exist. | 2326| 16000012 | The application is controlled. | 2327| 16000013 | The application is controlled by EDM. | 2328| 16000050 | Internal error. | 2329| 16000053 | The ability is not on the top of the UI. | 2330| 16000055 | Installation-free timed out. | 2331| 16200001 | The caller has been released. | 2332 2333For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 2334 2335**Example** 2336 2337```ts 2338import UIAbility from '@ohos.app.ability.UIAbility'; 2339import Want from '@ohos.app.ability.Want'; 2340import StartOptions from '@ohos.app.ability.StartOptions'; 2341import { BusinessError } from '@ohos.base'; 2342 2343export default class EntryAbility extends UIAbility { 2344 2345 onForeground() { 2346 let want: Want = { 2347 deviceId: '', 2348 bundleName: 'com.example.myapplication', 2349 abilityName: 'EntryAbility' 2350 }; 2351 let accountId = 100; 2352 let options: StartOptions = { 2353 windowMode: 0 2354 }; 2355 2356 try { 2357 this.context.startAbilityWithAccount(want, accountId, options) 2358 .then(() => { 2359 // Carry out normal service processing. 2360 console.info('startAbilityWithAccount succeed'); 2361 }) 2362 .catch((err: BusinessError) => { 2363 // Process service logic errors. 2364 console.error(`startAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`); 2365 }); 2366 } catch (err) { 2367 // Process input parameter errors. 2368 let code = (err as BusinessError).code; 2369 let message = (err as BusinessError).message; 2370 console.error(`startAbilityWithAccount failed, code is ${code}, message is ${message}`); 2371 } 2372 } 2373} 2374``` 2375 2376## UIAbilityContext.setMissionLabel 2377 2378setMissionLabel(label: string, callback: AsyncCallback<void>): void 2379 2380Sets a label for this UIAbility in the mission. This API uses an asynchronous callback to return the result. 2381 2382**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2383 2384**Parameters** 2385 2386| Name| Type| Mandatory| Description| 2387| -------- | -------- | -------- | -------- | 2388| label | string | Yes| Label of the ability to set.| 2389| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 2390 2391**Error codes** 2392 2393| ID| Error Message| 2394| ------- | -------------------------------- | 2395| 16000011 | The context does not exist. | 2396| 16000050 | Internal error. | 2397 2398For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 2399 2400**Example** 2401 2402```ts 2403import UIAbility from '@ohos.app.ability.UIAbility'; 2404import Want from '@ohos.app.ability.Want'; 2405import AbilityConstant from '@ohos.app.ability.AbilityConstant'; 2406import { BusinessError } from '@ohos.base'; 2407 2408export default class EntryAbility extends UIAbility { 2409 2410 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 2411 this.context.setMissionLabel('test', (result: BusinessError) => { 2412 console.info(`setMissionLabel: ${JSON.stringify(result)}`); 2413 }); 2414 } 2415} 2416``` 2417 2418## UIAbilityContext.setMissionLabel 2419 2420setMissionLabel(label: string): Promise<void> 2421 2422Sets a label for this UIAbility in the mission. This API uses a promise to return the result. 2423 2424**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2425 2426**Parameters** 2427 2428| Name| Type| Mandatory| Description| 2429| -------- | -------- | -------- | -------- | 2430| label | string | Yes| Label of the ability to set.| 2431 2432**Return value** 2433 2434| Type| Description| 2435| -------- | -------- | 2436| Promise<void> | Promise used to return the result.| 2437 2438**Error codes** 2439 2440| ID| Error Message| 2441| ------- | -------------------------------- | 2442| 16000011 | The context does not exist. | 2443| 16000050 | Internal error. | 2444 2445For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 2446 2447**Example** 2448 2449 ```ts 2450import UIAbility from '@ohos.app.ability.UIAbility'; 2451import Want from '@ohos.app.ability.Want'; 2452import AbilityConstant from '@ohos.app.ability.AbilityConstant'; 2453import { BusinessError } from '@ohos.base'; 2454 2455export default class EntryAbility extends UIAbility { 2456 2457 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 2458 this.context.setMissionLabel('test').then(() => { 2459 console.info('success'); 2460 }).catch((err: BusinessError) => { 2461 let code = (err as BusinessError).code; 2462 let message = (err as BusinessError).message; 2463 console.error(`setMissionLabel failed, code is ${code}, message is ${message}`); 2464 }); 2465 } 2466} 2467 ``` 2468## UIAbilityContext.setMissionIcon 2469 2470setMissionIcon(icon: image.PixelMap, callback: AsyncCallback\<void>): void 2471 2472Sets an icon for this ability in the mission. This API uses an asynchronous callback to return the result. The maximum size of the icon is 600 MB. 2473 2474**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2475 2476**System API**: This is a system API and cannot be called by third-party applications. 2477 2478**Parameters** 2479 2480| Name| Type| Mandatory| Description| 2481| -------- | -------- | -------- | -------- | 2482| icon | image.PixelMap | Yes| Icon of the ability to set.| 2483| callback | AsyncCallback\<void> | Yes| Callback used to return the result.| 2484 2485**Error codes** 2486 2487| ID| Error Message| 2488| ------- | -------------------------------- | 2489| 16000011 | The context does not exist. | 2490| 16000050 | Internal error. | 2491 2492For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 2493 2494**Example** 2495 2496```ts 2497import UIAbility from '@ohos.app.ability.UIAbility'; 2498import { BusinessError } from '@ohos.base'; 2499import image from '@ohos.multimedia.image'; 2500 2501export default class EntryAbility extends UIAbility { 2502 onForeground() { 2503 let imagePixelMap: image.PixelMap; 2504 let color = new ArrayBuffer(0); 2505 image.createPixelMap(color, { 2506 size: { 2507 height: 100, 2508 width: 100 2509 } 2510 }).then((data) => { 2511 imagePixelMap = data; 2512 this.context.setMissionIcon(imagePixelMap, (err: BusinessError) => { 2513 console.error(`setMissionLabel failed, code is ${err.code}, message is ${err.message}`); 2514 }) 2515 }) 2516 .catch((err: BusinessError) => { 2517 console.error(`createPixelMap failed, code is ${err.code}, message is ${err.message}`); 2518 }); 2519 } 2520} 2521``` 2522 2523 2524## UIAbilityContext.setMissionIcon 2525 2526setMissionIcon(icon: image.PixelMap): Promise\<void> 2527 2528Sets an icon for this ability in the mission. This API uses a promise to return the result. The maximum size of the icon is 600 MB. 2529 2530**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2531 2532**System API**: This is a system API and cannot be called by third-party applications. 2533 2534**Parameters** 2535 2536| Name| Type| Mandatory| Description| 2537| -------- | -------- | -------- | -------- | 2538| icon | image.PixelMap | Yes| Icon of the ability to set.| 2539 2540**Return value** 2541 2542| Type| Description| 2543| -------- | -------- | 2544| Promise<void> | Promise used to return the result.| 2545 2546**Error codes** 2547 2548| ID| Error Message| 2549| ------- | -------------------------------- | 2550| 16000011 | The context does not exist. | 2551| 16000050 | Internal error. | 2552 2553For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 2554 2555**Example** 2556 2557 ```ts 2558 import UIAbility from '@ohos.app.ability.UIAbility'; 2559 import { BusinessError } from '@ohos.base'; 2560 import image from '@ohos.multimedia.image'; 2561 2562 export default class EntryAbility extends UIAbility { 2563 onForeground() { 2564 let imagePixelMap: image.PixelMap; 2565 let color = new ArrayBuffer(0); 2566 image.createPixelMap(color, { 2567 size: { 2568 height: 100, 2569 width: 100 2570 } 2571 }).then((data) => { 2572 imagePixelMap = data; 2573 this.context.setMissionIcon(imagePixelMap) 2574 .then(() => { 2575 console.info('setMissionIcon succeed'); 2576 }) 2577 .catch((err: BusinessError) => { 2578 console.error(`setMissionLabel failed, code is ${err.code}, message is ${err.message}`); 2579 }); 2580 }) 2581 .catch((err: BusinessError) => { 2582 console.error(`createPixelMap failed, code is ${err.code}, message is ${err.message}`); 2583 }); 2584 } 2585 } 2586 ``` 2587 2588## UIAbilityContext.setMissionContinueState<sup>10+</sup> 2589 2590setMissionContinueState(state: AbilityConstant.ContinueState, callback: AsyncCallback<void>): void 2591 2592Sets the mission continuation state of this UIAbility. This API uses an asynchronous callback to return the result. 2593 2594**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2595 2596**Parameters** 2597 2598| Name| Type| Mandatory| Description| 2599| -------- | -------- | -------- | -------- | 2600| state | [AbilityConstant.ContinueState](js-apis-app-ability-abilityConstant.md#abilityconstantcontinuestate10) | Yes| Mission continuation state.| 2601| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 2602 2603**Error codes** 2604 2605| ID| Error Message| 2606| ------- | -------------------------------- | 2607| 16000011 | The context does not exist. | 2608| 16000050 | Internal error. | 2609 2610For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 2611 2612**Example** 2613 2614```ts 2615import UIAbility from '@ohos.app.ability.UIAbility'; 2616import AbilityConstant from '@ohos.app.ability.AbilityConstant'; 2617import { BusinessError } from '@ohos.base'; 2618 2619export default class EntryAbility extends UIAbility { 2620 onForeground() { 2621 this.context.setMissionContinueState(AbilityConstant.ContinueState.INACTIVE, (result: BusinessError) => { 2622 console.info(`setMissionContinueState: ${JSON.stringify(result)}`); 2623 }); 2624 } 2625} 2626``` 2627 2628## UIAbilityContext.setMissionContinueState<sup>10+</sup> 2629 2630setMissionContinueState(state: AbilityConstant.ContinueState): Promise<void> 2631 2632Sets the mission continuation state of this UIAbility. This API uses a promise to return the result. 2633 2634**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2635 2636**Parameters** 2637 2638| Name| Type| Mandatory| Description| 2639| -------- | -------- | -------- | -------- | 2640| state | [AbilityConstant.ContinueState](js-apis-app-ability-abilityConstant.md#abilityconstantcontinuestate10) | Yes| Mission continuation state.| 2641 2642**Return value** 2643 2644| Type| Description| 2645| -------- | -------- | 2646| Promise<void> | Promise used to return the result.| 2647 2648**Error codes** 2649 2650| ID| Error Message| 2651| ------- | -------------------------------- | 2652| 16000011 | The context does not exist. | 2653| 16000050 | Internal error. | 2654 2655For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 2656 2657**Example** 2658 2659```ts 2660import UIAbility from '@ohos.app.ability.UIAbility'; 2661import AbilityConstant from '@ohos.app.ability.AbilityConstant'; 2662import { BusinessError } from '@ohos.base'; 2663 2664export default class EntryAbility extends UIAbility { 2665 onForeground() { 2666 this.context.setMissionContinueState(AbilityConstant.ContinueState.INACTIVE).then(() => { 2667 console.info('success'); 2668 }).catch((err: BusinessError) => { 2669 console.error(`setMissionContinueState failed, code is ${err.code}, message is ${err.message}`); 2670 }); 2671 } 2672} 2673``` 2674 2675## UIAbilityContext.restoreWindowStage 2676 2677restoreWindowStage(localStorage: LocalStorage): void 2678 2679Restores the WindowStage data in the UIAbility. 2680 2681**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2682 2683**Parameters** 2684 2685| Name| Type| Mandatory| Description| 2686| -------- | -------- | -------- | -------- | 2687| localStorage | LocalStorage | Yes| Storage used to store the restored window stage.| 2688 2689**Error codes** 2690 2691| ID| Error Message| 2692| ------- | -------------------------------- | 2693| 16000011 | The context does not exist. | 2694| 16000050 | Internal error. | 2695 2696For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 2697 2698**Example** 2699 2700```ts 2701import UIAbility from '@ohos.app.ability.UIAbility'; 2702 2703export default class EntryAbility extends UIAbility { 2704 onForeground() { 2705 let storage = new LocalStorage(); 2706 this.context.restoreWindowStage(storage); 2707 } 2708} 2709``` 2710 2711## UIAbilityContext.isTerminating 2712 2713isTerminating(): boolean 2714 2715Checks whether this UIAbility is in the terminating state. 2716 2717**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2718 2719**Return value** 2720 2721| Type| Description| 2722| -------- | -------- | 2723| boolean| The value **true** means that the UIAbility is in the terminating state, and **false** means the opposite.| 2724 2725**Error codes** 2726 2727| ID| Error Message| 2728| ------- | -------------------------------- | 2729| 16000011 | The context does not exist. | 2730 2731For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 2732 2733**Example** 2734 2735```ts 2736import UIAbility from '@ohos.app.ability.UIAbility'; 2737 2738export default class EntryAbility extends UIAbility { 2739 onForeground() { 2740 let isTerminating: boolean = this.context.isTerminating(); 2741 console.info(`ability state is ${isTerminating}`); 2742 } 2743} 2744``` 2745 2746## UIAbilityContext.requestDialogService 2747 2748requestDialogService(want: Want, result: AsyncCallback<dialogRequest.RequestResult>): void 2749 2750Starts a ServiceExtensionAbility that supports modal dialog boxes. After the ServiceExtensionAbility is started, the application displays a modal dialog box. You can call [setRequestResult](js-apis-app-ability-dialogRequest.md#requestcallbacksetrequestresult) to obtain the result. 2751 2752Observe the following when using this API: 2753 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 2754 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 2755 - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 2756 2757**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2758 2759**Parameters** 2760 2761| Name| Type| Mandatory| Description| 2762| -------- | -------- | -------- | -------- | 2763| want |[Want](js-apis-app-ability-want.md) | Yes| Want information about the target ServiceExtensionAbility.| 2764| result | AsyncCallback<[dialogRequest.RequestResult](js-apis-app-ability-dialogRequest.md#requestresult)> | Yes| Callback used to return the result.| 2765 2766**Error codes** 2767 2768| ID| Error Message| 2769| ------- | -------------------------------- | 2770| 16000001 | The specified ability does not exist. | 2771| 16000002 | Incorrect ability type. | 2772| 16000004 | Can not start invisible component. | 2773| 16000005 | The specified process does not have the permission. | 2774| 16000006 | Cross-user operations are not allowed. | 2775| 16000008 | The crowdtesting application expires. | 2776| 16000009 | An ability cannot be started or stopped in Wukong mode. | 2777| 16000010 | The call with the continuation flag is forbidden. | 2778| 16000011 | The context does not exist. | 2779| 16000012 | The application is controlled. | 2780| 16000013 | The application is controlled by EDM. | 2781| 16000050 | Internal error. | 2782| 16000053 | The ability is not on the top of the UI. | 2783| 16000055 | Installation-free timed out. | 2784| 16200001 | The caller has been released. | 2785 2786For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 2787 2788**Example** 2789 2790```ts 2791import UIAbility from '@ohos.app.ability.UIAbility'; 2792import dialogRequest from '@ohos.app.ability.dialogRequest'; 2793import Want from '@ohos.app.ability.Want'; 2794import { BusinessError } from '@ohos.base'; 2795 2796export default class EntryAbility extends UIAbility { 2797 onForeground() { 2798 let want: Want = { 2799 deviceId: '', 2800 bundleName: 'com.example.myapplication', 2801 abilityName: 'AuthAccountServiceExtension' 2802 }; 2803 2804 try { 2805 this.context.requestDialogService(want, (err: BusinessError, result: dialogRequest.RequestResult) => { 2806 if (err.code) { 2807 // Process service logic errors. 2808 console.error(`requestDialogService failed, code is ${err.code}, message is ${err.message}`); 2809 return; 2810 } 2811 // Carry out normal service processing. 2812 console.info(`requestDialogService succeed, result = ${JSON.stringify(result)}`); 2813 }); 2814 } catch (err) { 2815 // Process input parameter errors. 2816 let code = (err as BusinessError).code; 2817 let message = (err as BusinessError).message; 2818 console.error(`requestDialogService failed, code is ${code}, message is ${message}`); 2819 } 2820 } 2821} 2822``` 2823 2824 ## UIAbilityContext.requestDialogService 2825 2826requestDialogService(want: Want): Promise<dialogRequest.RequestResult> 2827 2828Starts a ServiceExtensionAbility that supports modal dialog boxes. After the ServiceExtensionAbility is started, the application displays a modal dialog box. You can call [setRequestResult](js-apis-app-ability-dialogRequest.md#requestcallbacksetrequestresult) to obtain the result, which is returned to the caller in promise mode. 2829 2830Observe the following when using this API: 2831 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 2832 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 2833 - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 2834 2835**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2836 2837**Parameters** 2838 2839| Name| Type| Mandatory| Description| 2840| -------- | -------- | -------- | -------- | 2841| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ServiceExtensionAbility.| 2842 2843 2844**Return value** 2845 2846| Type| Description| 2847| -------- | -------- | 2848| Promise<[dialogRequest.RequestResult](js-apis-app-ability-dialogRequest.md)> | Promise used to return the result. 2849 2850**Error codes** 2851 2852| ID| Error Message| 2853| ------- | -------------------------------- | 2854| 16000001 | The specified ability does not exist. | 2855| 16000002 | Incorrect ability type. | 2856| 16000004 | Can not start invisible component. | 2857| 16000005 | The specified process does not have the permission. | 2858| 16000006 | Cross-user operations are not allowed. | 2859| 16000008 | The crowdtesting application expires. | 2860| 16000009 | An ability cannot be started or stopped in Wukong mode. | 2861| 16000010 | The call with the continuation flag is forbidden. | 2862| 16000011 | The context does not exist. | 2863| 16000012 | The application is controlled. | 2864| 16000013 | The application is controlled by EDM. | 2865| 16000050 | Internal error. | 2866| 16000053 | The ability is not on the top of the UI. | 2867| 16000055 | Installation-free timed out. | 2868| 16200001 | The caller has been released. | 2869 2870For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 2871 2872**Example** 2873 2874```ts 2875import UIAbility from '@ohos.app.ability.UIAbility'; 2876import dialogRequest from '@ohos.app.ability.dialogRequest'; 2877import Want from '@ohos.app.ability.Want'; 2878import { BusinessError } from '@ohos.base'; 2879 2880export default class EntryAbility extends UIAbility { 2881 2882 onForeground() { 2883 let want: Want = { 2884 bundleName: 'com.example.myapplication', 2885 abilityName: 'AuthAccountServiceExtension' 2886 }; 2887 2888 try { 2889 this.context.requestDialogService(want) 2890 .then((result: dialogRequest.RequestResult) => { 2891 // Carry out normal service processing. 2892 console.info(`requestDialogService succeed, result = ${JSON.stringify(result)}`); 2893 }) 2894 .catch((err: BusinessError) => { 2895 // Process service logic errors. 2896 console.error(`requestDialogService failed, code is ${err.code}, message is ${err.message}`); 2897 }); 2898 } catch (err) { 2899 // Process input parameter errors. 2900 let code = (err as BusinessError).code; 2901 let message = (err as BusinessError).message; 2902 console.error(`requestDialogService failed, code is ${code}, message is ${message}`); 2903 } 2904 } 2905} 2906``` 2907 ## UIAbilityContext.startRecentAbility 2908 2909startRecentAbility(want: Want, callback: AsyncCallback<void>): void 2910 2911Starts an ability. If the ability has multiple instances, the latest instance is started. This API uses an asynchronous callback to return the result. 2912 2913Observe the following when using this API: 2914 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 2915 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 2916 - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 2917 2918**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2919 2920**System API**: This is a system API and cannot be called by third-party applications. 2921 2922**Parameters** 2923 2924| Name| Type| Mandatory| Description| 2925| -------- | -------- | -------- | -------- | 2926| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 2927| callback | AsyncCallback\<void> | Yes| Callback used to return the result.| 2928 2929**Error codes** 2930 2931For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 2932 2933| ID| Error Message| 2934| ------- | -------------------------------- | 2935| 16000001 | The specified ability does not exist. | 2936| 16000002 | Incorrect ability type. | 2937| 16000004 | Can not start invisible component. | 2938| 16000005 | The specified process does not have the permission. | 2939| 16000006 | Cross-user operations are not allowed. | 2940| 16000008 | The crowdtesting application expires. | 2941| 16000009 | An ability cannot be started or stopped in Wukong mode. | 2942| 16000010 | The call with the continuation flag is forbidden. | 2943| 16000011 | The context does not exist. | 2944| 16000012 | The application is controlled. | 2945| 16000013 | The application is controlled by EDM. | 2946| 16000050 | Internal error. | 2947| 16000053 | The ability is not on the top of the UI. | 2948| 16000055 | Installation-free timed out. | 2949| 16200001 | The caller has been released. | 2950 2951**Example** 2952 2953```ts 2954import UIAbility from '@ohos.app.ability.UIAbility'; 2955import Want from '@ohos.app.ability.Want'; 2956import { BusinessError } from '@ohos.base'; 2957 2958export default class EntryAbility extends UIAbility { 2959 2960 onForeground() { 2961 let want: Want = { 2962 bundleName: 'com.example.myapplication', 2963 abilityName: 'EntryAbility' 2964 }; 2965 2966 try { 2967 this.context.startRecentAbility(want, (err: BusinessError) => { 2968 if (err.code) { 2969 // Process service logic errors. 2970 console.error(`startRecentAbility failed, code is ${err.code}, message is ${err.message}`); 2971 return; 2972 } 2973 // Carry out normal service processing. 2974 console.info('startRecentAbility succeed'); 2975 }); 2976 } catch (err) { 2977 // Process input parameter errors. 2978 let code = (err as BusinessError).code; 2979 let message = (err as BusinessError).message; 2980 console.error(`startRecentAbility failed, code is ${code}, message is ${message}`); 2981 } 2982 } 2983} 2984``` 2985## UIAbilityContext.startRecentAbility 2986 2987startRecentAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void 2988 2989Starts an ability with the start options specified. If the ability has multiple instances, the latest instance is started. This API uses an asynchronous callback to return the result. 2990You can use this API to carry start options. 2991 2992Observe the following when using this API: 2993 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 2994 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 2995 - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 2996 2997**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2998 2999**System API**: This is a system API and cannot be called by third-party applications. 3000 3001**Parameters** 3002 3003| Name| Type| Mandatory| Description| 3004| -------- | -------- | -------- | -------- | 3005| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 3006| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| 3007| callback | AsyncCallback\<void> | Yes| Callback used to return the result.| 3008 3009**Error codes** 3010 3011For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 3012 3013| ID| Error Message| 3014| ------- | -------------------------------- | 3015| 16000001 | The specified ability does not exist. | 3016| 16000002 | Incorrect ability type. | 3017| 16000004 | Can not start invisible component. | 3018| 16000005 | The specified process does not have the permission. | 3019| 16000006 | Cross-user operations are not allowed. | 3020| 16000008 | The crowdtesting application expires. | 3021| 16000009 | An ability cannot be started or stopped in Wukong mode. | 3022| 16000010 | The call with the continuation flag is forbidden. | 3023| 16000011 | The context does not exist. | 3024| 16000012 | The application is controlled. | 3025| 16000013 | The application is controlled by EDM. | 3026| 16000050 | Internal error. | 3027| 16000053 | The ability is not on the top of the UI. | 3028| 16000055 | Installation-free timed out. | 3029| 16200001 | The caller has been released. | 3030 3031**Example** 3032 3033```ts 3034import UIAbility from '@ohos.app.ability.UIAbility'; 3035import Want from '@ohos.app.ability.Want'; 3036import StartOptions from '@ohos.app.ability.StartOptions'; 3037import { BusinessError } from '@ohos.base'; 3038 3039export default class EntryAbility extends UIAbility { 3040 3041 onForeground() { 3042 let want: Want = { 3043 deviceId: '', 3044 bundleName: 'com.example.myapplication', 3045 abilityName: 'EntryAbility' 3046 }; 3047 let options: StartOptions = { 3048 windowMode: 0 3049 }; 3050 3051 try { 3052 this.context.startRecentAbility(want, options, (err: BusinessError) => { 3053 if (err.code) { 3054 // Process service logic errors. 3055 console.error(`startRecentAbility failed, code is ${err.code}, message is ${err.message}`); 3056 return; 3057 } 3058 // Carry out normal service processing. 3059 console.info('startRecentAbility succeed'); 3060 }); 3061 } catch (err) { 3062 // Process input parameter errors. 3063 let code = (err as BusinessError).code; 3064 let message = (err as BusinessError).message; 3065 console.error(`startRecentAbility failed, code is ${code}, message is ${message}`); 3066 } 3067 } 3068} 3069``` 3070## UIAbilityContext.startRecentAbility 3071 3072startRecentAbility(want: Want, options?: StartOptions): Promise<void> 3073 3074Starts an ability. If the ability has multiple instances, the latest instance is started. 3075This API uses a promise to return the result. 3076 3077Observe the following when using this API: 3078 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 3079 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 3080 - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 3081 3082**System capability**: SystemCapability.Ability.AbilityRuntime.Core 3083 3084**System API**: This is a system API and cannot be called by third-party applications. 3085 3086**Parameters** 3087 3088| Name| Type| Mandatory| Description| 3089| -------- | -------- | -------- | -------- | 3090| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 3091| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| 3092 3093**Error codes** 3094 3095For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 3096 3097| ID| Error Message| 3098| ------- | -------------------------------- | 3099| 16000001 | The specified ability does not exist. | 3100| 16000002 | Incorrect ability type. | 3101| 16000004 | Can not start invisible component. | 3102| 16000005 | The specified process does not have the permission. | 3103| 16000006 | Cross-user operations are not allowed. | 3104| 16000008 | The crowdtesting application expires. | 3105| 16000009 | An ability cannot be started or stopped in Wukong mode. | 3106| 16000010 | The call with the continuation flag is forbidden. | 3107| 16000011 | The context does not exist. | 3108| 16000012 | The application is controlled. | 3109| 16000013 | The application is controlled by EDM. | 3110| 16000050 | Internal error. | 3111| 16000053 | The ability is not on the top of the UI. | 3112| 16000055 | Installation-free timed out. | 3113| 16200001 | The caller has been released. | 3114 3115**Example** 3116 3117```ts 3118import UIAbility from '@ohos.app.ability.UIAbility'; 3119import Want from '@ohos.app.ability.Want'; 3120import StartOptions from '@ohos.app.ability.StartOptions'; 3121import { BusinessError } from '@ohos.base'; 3122 3123export default class EntryAbility extends UIAbility { 3124 3125 onForeground() { 3126 let want: Want = { 3127 bundleName: 'com.example.myapplication', 3128 abilityName: 'EntryAbility' 3129 }; 3130 let options: StartOptions = { 3131 windowMode: 0, 3132 }; 3133 3134 try { 3135 this.context.startRecentAbility(want, options) 3136 .then(() => { 3137 // Carry out normal service processing. 3138 console.info('startRecentAbility succeed'); 3139 }) 3140 .catch((err: BusinessError) => { 3141 // Process service logic errors. 3142 console.error(`startRecentAbility failed, code is ${err.code}, message is ${err.message}`); 3143 }); 3144 } catch (err) { 3145 // Process input parameter errors. 3146 let code = (err as BusinessError).code; 3147 let message = (err as BusinessError).message; 3148 console.error(`startRecentAbility failed, code is ${code}, message is ${message}`); 3149 } 3150 } 3151} 3152``` 3153 3154## UIAbilityContext.startAbilityByCallWithAccount<sup>10+</sup> 3155 3156startAbilityByCallWithAccount(want: Want, accountId: number): Promise<Caller> 3157 3158Starts an ability with the account ID specified and obtains the caller object for communicating with the ability. 3159 3160Observe the following when using this API: 3161 - If an application needs to call this API to start an ability that belongs to another user, it must have the **ohos.permission.ABILITY_BACKGROUND_COMMUNICATION** and **ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS** permissions. 3162 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 3163 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 3164 - The rules for using this API in the same-device and cross-device scenarios are different. For details, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 3165 3166**Required permissions**: ohos.permission.ABILITY_BACKGROUND_COMMUNICATION and ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 3167 3168**System capability**: SystemCapability.Ability.AbilityRuntime.Core 3169 3170**System API**: This is a system API and cannot be called by third-party applications. 3171 3172**Parameters** 3173 3174| Name| Type| Mandatory| Description| 3175| -------- | -------- | -------- | -------- | 3176| want | [Want](js-apis-app-ability-want.md) | Yes| Information about the ability to start, including **abilityName**, **moduleName**, **bundleName**, **deviceId** (optional), and **parameters** (optional). If **deviceId** is left blank or null, the local ability is started. If **parameters** is left blank or null, the ability is started in the background.| 3177| accountId | number | Yes| ID of a system account. The value **-1** indicates the current user. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountcount9).| 3178 3179**Return value** 3180 3181| Type| Description| 3182| -------- | -------- | 3183| Promise<Caller> | Promise used to return the caller object to communicate with.| 3184 3185**Error codes** 3186 3187| ID| Error Message| 3188| ------- | -------------------------------- | 3189| 16000001 | The specified ability does not exist. | 3190| 16000002 | Incorrect ability type. | 3191| 16000004 | Can not start invisible component. | 3192| 16000005 | Static permission denied. The specified process does not have the permission. | 3193| 16000006 | Cross-user operations are not allowed. | 3194| 16000008 | The crowdtesting application expires. | 3195| 16000011 | The context does not exist. | 3196| 16000012 | The application is controlled. | 3197| 16000013 | The application is controlled by EDM. | 3198| 16000050 | Internal error. | 3199| 16200001 | The caller has been released. | 3200 3201For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 3202 3203**Example** 3204 3205```ts 3206import UIAbility from '@ohos.app.ability.UIAbility'; 3207import { Caller } from '@ohos.app.ability.UIAbility'; 3208import Want from '@ohos.app.ability.Want'; 3209import { BusinessError } from '@ohos.base'; 3210 3211export default class EntryAbility extends UIAbility { 3212 3213 onForeground() { 3214 let caller: Caller; 3215 3216 // ID of a system account. The value -1 indicates the current user. 3217 let accountId = -1; 3218 3219 // Specify the ability to start. 3220 let want: Want = { 3221 bundleName: 'com.acts.actscalleeabilityrely', 3222 moduleName: 'entry', 3223 abilityName: 'EntryAbility', 3224 deviceId: '', 3225 parameters: { 3226 // If the value of 'ohos.aafwk.param.callAbilityToForeground' is true, the ability is started in the foreground. If the value is false or not set, the ability is started in the background. 3227 'ohos.aafwk.param.callAbilityToForeground': true 3228 } 3229 }; 3230 3231 try { 3232 this.context.startAbilityByCallWithAccount(want, accountId) 3233 .then((obj: Caller) => { 3234 // Carry out normal service processing. 3235 caller = obj; 3236 console.log('startAbilityByCallWithAccount succeed'); 3237 }).catch((error: BusinessError) => { 3238 // Process service logic errors. 3239 console.error('startAbilityByCallWithAccount failed, error.code: ${error.code}, error.message: ${error.message}'); 3240 }); 3241 } catch (paramError) { 3242 // Process input parameter errors. 3243 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 3244 } 3245 } 3246} 3247``` 3248 3249## UIAbilityContext.startAbilityAsCaller<sup>10+<sup> 3250 3251startAbilityAsCaller(want: Want, callback: AsyncCallback\<void>): void 3252 3253Starts an ability with the caller information specified. The caller information is carried in **want** and identified at the system service layer. The ability can obtain the caller information from the **want** parameter in the **onCreate** lifecycle callback. When this API is used to start an ability, the caller information carried in **want** is not overwritten by the current application information. The system service layer can obtain the initial caller information. This API uses an asynchronous callback to return the result. 3254 3255Observe the following when using this API: 3256 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 3257 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 3258 - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 3259 3260**System capability**: SystemCapability.Ability.AbilityRuntime.Core 3261 3262**System API**: This is a system API and cannot be called by third-party applications. 3263 3264**Parameters** 3265 3266| Name| Type| Mandatory| Description| 3267| -------- | -------- | -------- | -------- | 3268| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 3269| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the ability is started, **err** is **undefined**. Otherwise, **err** is an error object.| 3270 3271**Error codes** 3272 3273| ID| Error Message| 3274| ------- | -------------------------------- | 3275| 16000001 | The specified ability does not exist. | 3276| 16000002 | Incorrect ability type. | 3277| 16000004 | Can not start invisible component. | 3278| 16000005 | The specified process does not have the permission. | 3279| 16000006 | Cross-user operations are not allowed. | 3280| 16000008 | The crowdtesting application expires. | 3281| 16000009 | An ability cannot be started or stopped in Wukong mode. | 3282| 16000010 | The call with the continuation flag is forbidden. | 3283| 16000011 | The context does not exist. | 3284| 16000012 | The application is controlled. | 3285| 16000013 | The application is controlled by EDM. | 3286| 16000050 | Internal error. | 3287| 16000053 | The ability is not on the top of the UI. | 3288| 16000055 | Installation-free timed out. | 3289| 16200001 | The caller has been released. | 3290 3291For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 3292 3293**Example** 3294 3295```ts 3296import UIAbility from '@ohos.app.ability.UIAbility'; 3297import AbilityConstant from '@ohos.app.ability.AbilityConstant'; 3298import Want from '@ohos.app.ability.Want'; 3299 3300export default class EntryAbility extends UIAbility { 3301 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 3302 // want contains the information about the caller who starts the application. 3303 let localWant: Want = want; 3304 localWant.bundleName = 'com.example.demo'; 3305 localWant.moduleName = 'entry'; 3306 localWant.abilityName = 'TestAbility'; 3307 3308 // Start a new ability using the caller information. 3309 this.context.startAbilityAsCaller(localWant, (err) => { 3310 if (err && err.code != 0) { 3311 console.error('startAbilityAsCaller failed, err:' + JSON.stringify(err)); 3312 } else { 3313 console.log('startAbilityAsCaller success.'); 3314 } 3315 }) 3316 } 3317} 3318 3319``` 3320 3321## UIAbilityContext.startAbilityAsCaller<sup>10+<sup> 3322 3323startAbilityAsCaller(want: Want, options: StartOptions, callback: AsyncCallback\<void>): void 3324 3325Starts an ability with the caller information and start options specified. The caller information is carried in **want** and identified at the system service layer. The ability can obtain the caller information from the **want** parameter in the **onCreate** lifecycle callback. When this API is used to start an ability, the caller information carried in **want** is not overwritten by the current application information. The system service layer can obtain the initial caller information. This API uses an asynchronous callback to return the result. 3326 3327Observe the following when using this API: 3328 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 3329 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 3330 - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 3331 3332**System capability**: SystemCapability.Ability.AbilityRuntime.Core 3333 3334**System API**: This is a system API and cannot be called by third-party applications. 3335 3336**Parameters** 3337 3338| Name| Type| Mandatory| Description| 3339| -------- | -------- | -------- | -------- | 3340| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 3341| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| 3342| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the ability is started, **err** is **undefined**. Otherwise, **err** is an error object.| 3343 3344**Error codes** 3345 3346| ID| Error Message| 3347| ------- | -------------------------------- | 3348| 16000001 | The specified ability does not exist. | 3349| 16000004 | Can not start invisible component. | 3350| 16000005 | The specified process does not have the permission. | 3351| 16000006 | Cross-user operations are not allowed. | 3352| 16000008 | The crowdtesting application expires. | 3353| 16000009 | An ability cannot be started or stopped in Wukong mode. | 3354| 16000011 | The context does not exist. | 3355| 16000012 | The application is controlled. | 3356| 16000013 | The application is controlled by EDM. | 3357| 16000050 | Internal error. | 3358| 16000053 | The ability is not on the top of the UI. | 3359| 16000055 | Installation-free timed out. | 3360| 16200001 | The caller has been released. | 3361 3362For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 3363 3364**Example** 3365 3366```ts 3367import UIAbility from '@ohos.app.ability.UIAbility'; 3368import AbilityConstant from '@ohos.app.ability.AbilityConstant'; 3369import StartOptions from '@ohos.app.ability.StartOptions'; 3370import Want from '@ohos.app.ability.Want'; 3371 3372export default class EntryAbility extends UIAbility { 3373 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 3374 // want contains the information about the caller who starts the application. 3375 let localWant: Want = want; 3376 localWant.bundleName = 'com.example.demo'; 3377 localWant.moduleName = 'entry'; 3378 localWant.abilityName = 'TestAbility'; 3379 3380 let option: StartOptions = { 3381 displayId: 0 3382 } 3383 3384 // Start a new ability using the caller information. 3385 this.context.startAbilityAsCaller(localWant, option, (err) => { 3386 if (err && err.code != 0) { 3387 console.error('startAbilityAsCaller failed, err:' + JSON.stringify(err)); 3388 } else { 3389 console.log('startAbilityAsCaller success.'); 3390 } 3391 }) 3392 } 3393} 3394 3395``` 3396 3397## UIAbilityContext.startAbilityAsCaller<sup>10+<sup> 3398 3399startAbilityAsCaller(want: Want, options?: StartOptions): Promise\<void> 3400 3401Starts an ability with the caller information specified. The caller information is carried in **want** and identified at the system service layer. The ability can obtain the caller information from the **want** parameter in the **onCreate** lifecycle callback. When this API is used to start an ability, the caller information carried in **want** is not overwritten by the current application information. The system service layer can obtain the initial caller information. This API uses a promise to return the result. 3402 3403Observe the following when using this API: 3404 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 3405 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 3406 - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 3407 3408**System capability**: SystemCapability.Ability.AbilityRuntime.Core 3409 3410**System API**: This is a system API and cannot be called by third-party applications. 3411 3412**Parameters** 3413 3414| Name| Type| Mandatory| Description| 3415| -------- | -------- | -------- | -------- | 3416| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 3417| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| 3418 3419**Return value** 3420 3421| Type| Description| 3422| -------- | -------- | 3423| Promise<void> | Promise that returns no value.| 3424 3425**Error codes** 3426 3427| ID| Error Message| 3428| ------- | -------------------------------- | 3429| 16000001 | The specified ability does not exist. | 3430| 16000002 | Incorrect ability type. | 3431| 16000004 | Can not start invisible component. | 3432| 16000005 | The specified process does not have the permission. | 3433| 16000006 | Cross-user operations are not allowed. | 3434| 16000008 | The crowdtesting application expires. | 3435| 16000009 | An ability cannot be started or stopped in Wukong mode. | 3436| 16000010 | The call with the continuation flag is forbidden. | 3437| 16000011 | The context does not exist. | 3438| 16000012 | The application is controlled. | 3439| 16000013 | The application is controlled by EDM. | 3440| 16000050 | Internal error. | 3441| 16000053 | The ability is not on the top of the UI. | 3442| 16000055 | Installation-free timed out. | 3443| 16200001 | The caller has been released. | 3444 3445For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 3446 3447**Example** 3448 3449```ts 3450import UIAbility from '@ohos.app.ability.UIAbility'; 3451import AbilityConstant from '@ohos.app.ability.AbilityConstant'; 3452import StartOptions from '@ohos.app.ability.StartOptions'; 3453import Want from '@ohos.app.ability.Want'; 3454import { BusinessError } from '@ohos.base'; 3455 3456export default class EntryAbility extends UIAbility { 3457 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 3458 // want contains the information about the caller who starts the application. 3459 let localWant: Want = want; 3460 localWant.bundleName = 'com.example.demo'; 3461 localWant.moduleName = 'entry'; 3462 localWant.abilityName = 'TestAbility'; 3463 3464 let option: StartOptions = { 3465 displayId: 0 3466 } 3467 3468 // Start a new ability using the caller information. 3469 this.context.startAbilityAsCaller(localWant, option) 3470 .then(() => { 3471 console.log('startAbilityAsCaller success.'); 3472 }) 3473 .catch((err: BusinessError) => { 3474 console.error('startAbilityAsCaller failed, err:' + JSON.stringify(err)); 3475 }) 3476 } 3477} 3478 3479``` 3480 3481## UIAbilityContext.reportDrawnCompleted<sup>10+</sup> 3482 3483reportDrawnCompleted(callback: AsyncCallback\<void>): void 3484 3485Reports an event indicating that page loading is complete (**loadContent()** is successfully called). This API uses an asynchronous callback to return the result. 3486 **System capability**: SystemCapability.Ability.AbilityRuntime.Core 3487 3488**Parameters** 3489 3490| Name| Type| Mandatory| Description| 3491| -------- | -------- | -------- | -------- | 3492| callback | AsyncCallback<void> | Yes| Callback used to report that page loading is complete.| 3493 3494**Error codes** 3495 3496| ID| Error Message| 3497| ------- | -------------------------------- | 3498| 16000011 | The context does not exist. | 3499| 16000050 | Internal error. | 3500 3501For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 3502 3503**Example** 3504 3505 ```ts 3506import UIAbility from '@ohos.app.ability.UIAbility'; 3507import window from '@ohos.window'; 3508import { BusinessError } from '@ohos.base'; 3509 3510export default class EntryAbility extends UIAbility { 3511 onWindowStageCreate(windowStage: window.WindowStage) { 3512 windowStage.loadContent('pages/Index', (err, data) => { 3513 if (err.code) { 3514 return; 3515 } 3516 try { 3517 this.context.reportDrawnCompleted((err) => { 3518 if (err.code) { 3519 // Process service logic errors. 3520 console.error(`reportDrawnCompleted failed, code is ${err.code}, message is ${err.message}`); 3521 return; 3522 } 3523 // Carry out normal service processing. 3524 console.info('reportDrawnCompleted succeed'); 3525 }); 3526 } catch (err) { 3527 // Capture the synchronization parameter error. 3528 let code = (err as BusinessError).code; 3529 let message = (err as BusinessError).message; 3530 console.error(`reportDrawnCompleted failed, code is ${code}, message is ${message}`); 3531 } 3532 }); 3533 console.log("MainAbility onWindowStageCreate") 3534 } 3535}; 3536 ``` 3537 3538## UIAbilityContext.startAbilityByType<sup>11+</sup> 3539 3540startAbilityByType(type: string, wantParam: Record<string, Object>, 3541 abilityStartCallback: AbilityStartCallback, callback: AsyncCallback\<void>) : void 3542 3543Implicitly starts a given type of UIExtensionAbility. This API uses an asynchronous callback to return the result. 3544 3545**System capability**: SystemCapability.Ability.AbilityRuntime.Core 3546 3547**Parameters** 3548 3549| Name| Type| Mandatory| Description| 3550| -------- | -------- | -------- | -------- | 3551| type | string | Yes| Type of the UIExtensionAbility to start.| 3552| wantParam | {[key: string]: any} | Yes| Extended parameter.| 3553| abilityStartCallback | [AbilityStartCallback](js-apis-inner-application-abilityStartCallback.md) | Yes| Callback to be invoked when the startup fails.| 3554| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 3555 3556**Error codes** 3557 3558| ID| Error Message| 3559| ------- | -------------------------------- | 3560| 16000001 | The specified ability does not exist. | 3561| 16000002 | Incorrect ability type. | 3562| 16000004 | Can not start invisible component. | 3563| 16000050 | Internal error. | 3564| 16200001 | The caller has been released. | 3565 3566For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 3567 3568**Example** 3569 3570 ```ts 3571 import common from '@ohos.app.ability.common'; 3572 let context = getContext(this) as common.UIAbilityContext; 3573 let wantParam: Record<string, Object> = { 3574 'time':'2023-10-23 20:45', 3575 }; 3576 let abilityStartCallback: common.AbilityStartCallback = { 3577 onError: (code: number, name: string, message: string) => { 3578 console.log(`code:` + code + `name:` + name + `message:` + message); 3579 } 3580 } 3581 context.startAbilityByType("photoEditor", wantParam, abilityStartCallback, (err) => { 3582 if (err) { 3583 console.error(`startAbilityByType fail, err: ${JSON.stringify(err)}`); 3584 } else { 3585 console.log(`success`); 3586 } 3587 }); 3588 ``` 3589 3590## UIAbilityContext.startAbilityByType<sup>11+</sup> 3591 3592startAbilityByType(type: string, wantParam: Record<string, Object>, 3593 abilityStartCallback: AbilityStartCallback) : Promise\<void> 3594 3595Implicitly starts a given type of UIExtensionAbility. This API uses a promise to return the result. 3596 3597**System capability**: SystemCapability.Ability.AbilityRuntime.Core 3598 3599**Parameters** 3600 3601| Name| Type| Mandatory| Description| 3602| -------- | -------- | -------- | -------- | 3603| type | string | Yes| Type of the UIExtensionAbility to start.| 3604| wantParam | {[key: string]: Object} | Yes| Extended parameter.| 3605| abilityStartCallback | [AbilityStartCallback](js-apis-inner-application-abilityStartCallback.md) | Yes| Callback to be invoked when the startup fails.| 3606 3607**Return value** 3608 3609| Type| Description| 3610| -------- | -------- | 3611| Promise<void> | Promise that returns no value.| 3612 3613**Error codes** 3614 3615| ID| Error Message| 3616| ------- | -------------------------------- | 3617| 16000001 | The specified ability does not exist. | 3618| 16000002 | Incorrect ability type. | 3619| 16000004 | Can not start invisible component. | 3620| 16000050 | Internal error. | 3621| 16200001 | The caller has been released. | 3622 3623For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 3624 3625**Example** 3626 3627 ```ts 3628 import common from '@ohos.app.ability.common'; 3629 import { BusinessError } from '@ohos.base'; 3630 let context = getContext(this) as common.UIAbilityContext; 3631 let wantParam: Record<string, Object> = { 3632 'time':'2023-10-23 20:45', 3633 }; 3634 let abilityStartCallback: common.AbilityStartCallback = { 3635 onError: (code: number, name: string, message: string) => { 3636 console.log(`code:` + code + `name:` + name + `message:` + message); 3637 } 3638 } 3639 context.startAbilityByType("photoEditor", wantParam, abilityStartCallback).then(() => { 3640 console.log(`startAbilityByType success`); 3641 }).catch((err: BusinessError) => { 3642 console.error(`startAbilityByType fail, err: ${JSON.stringify(err)}`); 3643 }) 3644 ``` 3645 3646## UIAbilityContext.requestModalUIExtension<sup>11+<sup> 3647 3648requestModalUIExtension(pickerWant: Want): Promise\<void> 3649 3650Requests a modal window (expressed by a UIExtensionAbility). The information about the requester and target is carried by **want**. The system determines the type of the modal window to start by comparing **bundleName** of the requester carried in **want** with that of the application currently running in the foreground. This API uses a promise to return the result. 3651 3652- If the values of **bundleName** are the same, users must interact with the modal window before they can return to the current application screen. 3653- If the values of **bundleName** are different, users must interact with the modal window before they can return to the current system screen. 3654 3655Observe the following when using this API: 3656- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 3657- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 3658 3659**System capability**: SystemCapability.Ability.AbilityRuntime.Core 3660 3661**System API**: This is a system API. 3662 3663**Parameters** 3664 3665| Name| Type| Mandatory| Description| 3666| -------- | -------- | -------- | -------- | 3667| want | [Want](js-apis-app-ability-want.md) | Yes| Want information used to start the modal window.| 3668 3669**Return value** 3670 3671| Type| Description| 3672| -------- | -------- | 3673| Promise<void> | Promise that returns no value.| 3674 3675**Error codes** 3676| ID| Error Message| 3677| ------- | -------------------------------- | 3678| 401 | If the input parameter is not valid parameter. | 3679| 16000001 | The specified ability does not exist. | 3680| 16000002 | Incorrect ability type. | 3681| 16000004 | Can not start invisible component. | 3682| 16000050 | Internal error. | 3683| 16200001 | The caller has been released. | 3684 3685For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 3686 3687**Example** 3688 3689```ts 3690import UIAbility from '@ohos.app.ability.UIAbility'; 3691import Want from '@ohos.app.ability.Want'; 3692import { BusinessError } from '@ohos.base'; 3693 3694export default class EntryAbility extends UIAbility { 3695 3696 onForeground() { 3697 let want: Want = { 3698 bundleName: 'com.example.myapplication', 3699 abilityName: 'requestModalUIExtension', 3700 moduleName: 'requestModalUIExtension', 3701 parameters: { 3702 bundleName: 'com.example.myapplication' 3703 } 3704 }; 3705 3706 try { 3707 this.context.requestModalUIExtension(want) 3708 .then(() => { 3709 // Carry out normal service processing. 3710 console.info('requestModalUIExtension succeed'); 3711 }) 3712 .catch((err: BusinessError) => { 3713 // Process service logic errors. 3714 console.error(`requestModalUIExtension failed, code is ${err.code}, message is ${err.message}`); 3715 }); 3716 } catch (err) { 3717 // Process input parameter errors. 3718 let code = (err as BusinessError).code; 3719 let message = (err as BusinessError).message; 3720 console.error(`requestModalUIExtension failed, code is ${code}, message is ${message}`); 3721 } 3722 } 3723} 3724``` 3725 3726## UIAbilityContext.requestModalUIExtension<sup>11+<sup> 3727requestModalUIExtension(pickerWant: Want, callback: AsyncCallback\<void>): void 3728 3729Requests a modal window (expressed by a UIExtensionAbility). The information about the requester and target is carried by **want**. The system determines the type of the modal window to start by comparing **bundleName** of the requester carried in **want** with that of the application currently running in the foreground. This API uses an asynchronous callback to return the result. 3730 3731- If the values of **bundleName** are the same, users must interact with the modal window before they can return to the current application screen. 3732- If the values of **bundleName** are different, users must interact with the modal window before they can return to the current system screen. 3733 3734Observe the following when using this API: 3735- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 3736- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 3737 3738**System capability**: SystemCapability.Ability.AbilityRuntime.Core 3739 3740**System API**: This is a system API. 3741 3742**Parameters** 3743 3744| Name| Type| Mandatory| Description| 3745| -------- | -------- | -------- | -------- | 3746| want | [Want](js-apis-app-ability-want.md) | Yes| Want information used to start the modal window.| 3747| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the UIExtensionAbility is started, **err** is **undefined**; otherwise, **err** is an error object.| 3748 3749**Error codes** 3750| ID| Error Message| 3751| ------- | -------------------------------- | 3752| 401 | If the input parameter is not valid parameter. | 3753| 16000001 | The specified ability does not exist. | 3754| 16000002 | Incorrect ability type. | 3755| 16000004 | Can not start invisible component. | 3756| 16000050 | Internal error. | 3757| 16200001 | The caller has been released. | 3758 3759For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 3760 3761**Example** 3762 3763```ts 3764import UIAbility from '@ohos.app.ability.UIAbility'; 3765import Want from '@ohos.app.ability.Want'; 3766import { BusinessError } from '@ohos.base'; 3767 3768export default class EntryAbility extends UIAbility { 3769 onForeground() { 3770 let want: Want = { 3771 bundleName: 'com.example.myapplication', 3772 abilityName: 'requestModalUIExtension', 3773 moduleName: 'requestModalUIExtension', 3774 parameters: { 3775 bundleName: 'com.example.myapplication' 3776 } 3777 }; 3778 3779 try { 3780 this.context.requestModalUIExtension(want, (err: BusinessError) => { 3781 if (err.code) { 3782 // Process service logic errors. 3783 console.error(`requestModalUIExtension failed, code is ${err.code}, message is ${err.message}`); 3784 return; 3785 } 3786 // Carry out normal service processing. 3787 console.info('requestModalUIExtension succeed'); 3788 }); 3789 } catch (err) { 3790 // Process input parameter errors. 3791 let code = (err as BusinessError).code; 3792 let message = (err as BusinessError).message; 3793 console.error(`requestModalUIExtension failed, code is ${code}, message is ${message}`); 3794 } 3795 } 3796} 3797``` 3798