1# AbilityDelegator 2 3The **AbilityDelegator** module provides APIs for managing [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#abilitymonitor-1) instances that are used to monitor the lifecycle state changes of a specified ability. You can use the APIs to add and remove **AbilityMonitor** instances, wait for an ability to reach the **onCreate** lifecycle state, set the waiting time, obtain the lifecycle state of an ability, obtain the top ability of the current application, and start an ability. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9## Modules to Import 10 11```ts 12import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 13``` 14 15## Usage 16 17An **AbilityDelegator** object is obtained by calling [getAbilityDelegator](js-apis-app-ability-abilityDelegatorRegistry.md#abilitydelegatorregistrygetabilitydelegator) in **AbilityDelegatorRegistry**. This API can be used only in the test environment. 18```ts 19import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 20``` 21 22## AbilityDelegator 23 24### addAbilityMonitor<sup>9+</sup> 25 26addAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\<void>): void 27 28Adds an **AbilityMonitor** instance. This API uses an asynchronous callback to return the result. 29 30**System capability**: SystemCapability.Ability.AbilityRuntime.Core 31 32**Parameters** 33 34| Name | Type | Mandatory| Description | 35| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 36| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 37| callback | AsyncCallback\<void> | Yes | Callback used to return the result. | 38 39**Error codes** 40 41| ID| Error Message| 42| ------- | -------- | 43| 16000100 | AddAbilityMonitor failed. | 44 45For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 46 47**Example** 48 49```ts 50import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 51import UIAbility from '@ohos.app.ability.UIAbility'; 52import { BusinessError } from '@ohos.base'; 53 54let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 55 56function onAbilityCreateCallback(data: UIAbility) { 57 console.info(`onAbilityCreateCallback, data: ${JSON.stringify(data)}`); 58} 59 60let monitor: AbilityDelegatorRegistry.AbilityMonitor = { 61 abilityName: 'abilityname', 62 onAbilityCreate: onAbilityCreateCallback 63}; 64abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 65abilityDelegator.addAbilityMonitor(monitor, (error: BusinessError) => { 66 console.error(`addAbilityMonitor fail, error: ${JSON.stringify(error)}`); 67}); 68``` 69 70### addAbilityMonitor<sup>9+</sup> 71 72addAbilityMonitor(monitor: AbilityMonitor): Promise\<void> 73 74Adds an **AbilityMonitor** instance. This API uses a promise to return the result. 75 76**System capability**: SystemCapability.Ability.AbilityRuntime.Core 77 78**Parameters** 79 80| Name | Type | Mandatory| Description | 81| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 82| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 83 84**Return value** 85 86| Type | Description | 87| -------------- | ------------------- | 88| Promise\<void> | Promise used to return the result.| 89 90**Error codes** 91 92| ID| Error Message| 93| ------- | -------- | 94| 16000100 | AddAbilityMonitor failed. | 95 96For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 97 98**Example** 99 100```ts 101import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 102import UIAbility from '@ohos.app.ability.UIAbility'; 103 104let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 105 106function onAbilityCreateCallback(data: UIAbility) { 107 console.info('onAbilityCreateCallback'); 108} 109 110let monitor: AbilityDelegatorRegistry.AbilityMonitor = { 111 abilityName: 'abilityname', 112 onAbilityCreate: onAbilityCreateCallback 113}; 114abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 115abilityDelegator.addAbilityMonitor(monitor).then(() => { 116 console.info('addAbilityMonitor promise'); 117}); 118``` 119 120### addAbilityMonitorSync<sup>10+</sup> 121 122addAbilityMonitorSync(monitor: AbilityMonitor): void 123 124Adds an **AbilityMonitor** instance. This API returns the result synchronously. 125 126**System capability**: SystemCapability.Ability.AbilityRuntime.Core 127 128**Parameters** 129 130| Name | Type | Mandatory| Description | 131| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 132| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 133 134**Error codes** 135 136| ID| Error Message| 137| ------- | -------- | 138| 16000100 | AddAbilityMonitorSync failed. | 139 140For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 141 142**Example** 143 144```ts 145import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 146import UIAbility from '@ohos.app.ability.UIAbility'; 147 148let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 149 150function onAbilityCreateCallback(data: UIAbility) { 151 console.info('onAbilityCreateCallback'); 152} 153 154let monitor: AbilityDelegatorRegistry.AbilityMonitor = { 155 abilityName: 'abilityname', 156 onAbilityCreate: onAbilityCreateCallback 157}; 158abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 159abilityDelegator.addAbilityMonitorSync(monitor); 160``` 161 162### removeAbilityMonitor<sup>9+</sup> 163 164removeAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\<void>): void 165 166Removes an **AbilityMonitor** instance. This API uses an asynchronous callback to return the result. 167 168**System capability**: SystemCapability.Ability.AbilityRuntime.Core 169 170**Parameters** 171 172| Name | Type | Mandatory| Description | 173| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 174| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 175| callback | AsyncCallback\<void> | Yes | Callback used to return the result. | 176 177**Error codes** 178 179| ID| Error Message| 180| ------- | -------- | 181| 16000100 | RemoveAbilityMonitor failed. | 182 183For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 184 185**Example** 186 187```ts 188import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 189import UIAbility from '@ohos.app.ability.UIAbility'; 190import { BusinessError } from '@ohos.base'; 191 192let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 193 194function onAbilityCreateCallback(data: UIAbility) { 195 console.info('onAbilityCreateCallback'); 196} 197 198let monitor: AbilityDelegatorRegistry.AbilityMonitor = { 199 abilityName: 'abilityname', 200 onAbilityCreate: onAbilityCreateCallback 201}; 202 203abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 204abilityDelegator.removeAbilityMonitor(monitor, (error: BusinessError) => { 205 console.error(`removeAbilityMonitor fail, error: ${JSON.stringify(error)}`); 206}); 207``` 208 209### removeAbilityMonitor<sup>9+</sup> 210 211removeAbilityMonitor(monitor: AbilityMonitor): Promise\<void> 212 213Removes an **AbilityMonitor** instance. This API uses a promise to return the result. 214 215**System capability**: SystemCapability.Ability.AbilityRuntime.Core 216 217**Parameters** 218 219| Name | Type | Mandatory| Description | 220| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 221| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 222 223**Return value** 224 225| Type | Description | 226| -------------- | ------------------- | 227| Promise\<void> | Promise used to return the result.| 228 229**Error codes** 230 231| ID| Error Message| 232| ------- | -------- | 233| 16000100 | RemoveAbilityMonitor failed. | 234 235For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 236 237- Example 238 239```ts 240import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 241import UIAbility from '@ohos.app.ability.UIAbility'; 242 243let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 244 245function onAbilityCreateCallback(data: UIAbility) { 246 console.info('onAbilityCreateCallback'); 247} 248 249let monitor: AbilityDelegatorRegistry.AbilityMonitor = { 250 abilityName: 'abilityname', 251 onAbilityCreate: onAbilityCreateCallback 252}; 253 254abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 255abilityDelegator.removeAbilityMonitor(monitor).then(() => { 256 console.info('removeAbilityMonitor promise'); 257}); 258``` 259 260### removeAbilityMonitorSync<sup>10+</sup> 261 262removeAbilityMonitorSync(monitor: AbilityMonitor): void 263 264Removes an **AbilityMonitor** instance. This API returns the result synchronously. 265 266**System capability**: SystemCapability.Ability.AbilityRuntime.Core 267 268**Parameters** 269 270| Name | Type | Mandatory| Description | 271| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 272| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 273 274**Error codes** 275 276| ID| Error Message| 277| ------- | -------- | 278| 16000100 | RemoveAbilityMonitorSync failed. | 279 280For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 281 282**Example** 283 284```ts 285import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 286import UIAbility from '@ohos.app.ability.UIAbility'; 287 288let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 289 290function onAbilityCreateCallback(data: UIAbility) { 291 console.info('onAbilityCreateCallback'); 292} 293 294let monitor: AbilityDelegatorRegistry.AbilityMonitor = { 295 abilityName: 'abilityname', 296 onAbilityCreate: onAbilityCreateCallback 297}; 298 299abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 300abilityDelegator.removeAbilityMonitorSync(monitor); 301``` 302 303### waitAbilityMonitor<sup>9+</sup> 304 305waitAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\<UIAbility>): void 306 307Waits for the **Ability** instance that matches the **AbilityMonitor** instance to reach the **onCreate** lifecycle state and returns the **Ability** instance. This API uses an asynchronous callback to return the result. 308 309**System capability**: SystemCapability.Ability.AbilityRuntime.Core 310 311**Parameters** 312 313| Name | Type | Mandatory| Description | 314| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 315| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 316| callback | AsyncCallback\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Yes | Callback used to return the result. | 317 318**Error codes** 319 320| ID| Error Message| 321| ------- | -------- | 322| 16000100 | WaitAbilityMonitor failed. | 323 324For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 325 326**Example** 327 328```ts 329import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 330import UIAbility from '@ohos.app.ability.UIAbility'; 331import { BusinessError } from '@ohos.base'; 332 333let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 334 335function onAbilityCreateCallback(data: UIAbility) { 336 console.info('onAbilityCreateCallback'); 337} 338 339let monitor: AbilityDelegatorRegistry.AbilityMonitor = { 340 abilityName: 'abilityname', 341 onAbilityCreate: onAbilityCreateCallback 342}; 343 344abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 345abilityDelegator.waitAbilityMonitor(monitor, (error : BusinessError, data : UIAbility) => { 346 if (error) { 347 console.error(`waitAbilityMonitor fail, error: ${JSON.stringify(error)}`); 348 } else { 349 console.log(`waitAbilityMonitor success, data: ${JSON.stringify(data)}`); 350 } 351}); 352``` 353 354### waitAbilityMonitor<sup>9+</sup> 355 356waitAbilityMonitor(monitor: AbilityMonitor, timeout: number, callback: AsyncCallback\<UIAbility>): void 357 358Waits a period of time for the **Ability** instance that matches the **AbilityMonitor** instance to reach the **onCreate** lifecycle state and returns the **Ability** instance. This API uses an asynchronous callback to return the result. 359 360**System capability**: SystemCapability.Ability.AbilityRuntime.Core 361 362**Parameters** 363 364| Name | Type | Mandatory| Description | 365| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 366| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 367| timeout | number | Yes | Maximum waiting time, in milliseconds. | 368| callback | AsyncCallback\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Yes | Callback used to return the result. | 369 370**Error codes** 371 372| ID| Error Message| 373| ------- | -------- | 374| 16000100 | WaitAbilityMonitor failed. | 375 376For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 377 378**Example** 379 380```ts 381import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 382import UIAbility from '@ohos.app.ability.UIAbility'; 383import { BusinessError } from '@ohos.base'; 384 385let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 386let timeout = 100; 387 388function onAbilityCreateCallback(data: UIAbility) { 389 console.info('onAbilityCreateCallback'); 390} 391 392let monitor: AbilityDelegatorRegistry.AbilityMonitor = { 393 abilityName: 'abilityname', 394 onAbilityCreate: onAbilityCreateCallback 395}; 396 397abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 398abilityDelegator.waitAbilityMonitor(monitor, timeout, (error : BusinessError, data : UIAbility) => { 399 if (error && error.code !== 0) { 400 console.error(`waitAbilityMonitor fail, error: ${JSON.stringify(error)}`); 401 } else { 402 console.log(`waitAbilityMonitor success, data: ${JSON.stringify(data)}`); 403 } 404}); 405``` 406 407 408 409### waitAbilityMonitor<sup>9+</sup> 410 411waitAbilityMonitor(monitor: AbilityMonitor, timeout?: number): Promise\<UIAbility> 412 413Waits a period of time for the **Ability** instance that matches the **AbilityMonitor** instance to reach the **onCreate** lifecycle state and returns the **Ability** instance. This API uses a promise to return the result. 414 415**System capability**: SystemCapability.Ability.AbilityRuntime.Core 416 417**Parameters** 418 419| Name | Type | Mandatory| Description | 420| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 421| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 422| timeout | number | No | Maximum waiting time, in milliseconds. | 423 424**Return value** 425 426| Type | Description | 427| ----------------------------------------------------------- | -------------------------- | 428| Promise\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Promise used to return the **Ability** instance.| 429 430**Error codes** 431 432| ID| Error Message| 433| ------- | -------- | 434| 16000100 | WaitAbilityMonitor failed. | 435 436For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 437 438**Example** 439 440```ts 441import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 442import UIAbility from '@ohos.app.ability.UIAbility'; 443 444let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 445 446function onAbilityCreateCallback(data: UIAbility) { 447 console.info('onAbilityCreateCallback'); 448} 449 450let monitor: AbilityDelegatorRegistry.AbilityMonitor = { 451 abilityName: 'abilityname', 452 onAbilityCreate: onAbilityCreateCallback 453}; 454 455abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 456abilityDelegator.waitAbilityMonitor(monitor).then((data : UIAbility) => { 457 console.info('waitAbilityMonitor promise'); 458}); 459``` 460 461### getAppContext<sup>9+</sup> 462 463getAppContext(): Context 464 465Obtains the application context. 466 467**System capability**: SystemCapability.Ability.AbilityRuntime.Core 468 469**Return value** 470 471| Type | Description | 472| ------------------------------------- | ------------------------------------------- | 473| [Context](js-apis-inner-application-context.md) | Application [context](js-apis-inner-application-context.md).| 474 475**Example** 476 477```ts 478import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 479 480let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 481 482abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 483let context = abilityDelegator.getAppContext(); 484``` 485 486### getAbilityState<sup>9+</sup> 487 488getAbilityState(ability: UIAbility): number 489 490Obtains the lifecycle state of an ability. 491 492**System capability**: SystemCapability.Ability.AbilityRuntime.Core 493 494**Parameters** 495 496| Name | Type | Mandatory| Description | 497| ------- | ------------------------------------------------- | ---- | --------------- | 498| ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes | Target ability.| 499 500**Return value** 501 502| Type | Description | 503| ------ | ------------------------------------------------------------ | 504| number | Lifecycle state of the ability. For details about the available enumerated values, see [AbilityLifecycleState](js-apis-application-abilityDelegatorRegistry.md#AbilityLifecycleState).| 505 506**Example** 507 508```ts 509import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 510import UIAbility from '@ohos.app.ability.UIAbility'; 511import { BusinessError } from '@ohos.base'; 512 513let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 514let ability: UIAbility; 515 516abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 517abilityDelegator.getCurrentTopAbility((err : BusinessError, data : UIAbility) => { 518 console.info('getCurrentTopAbility callback'); 519 ability = data; 520 let state = abilityDelegator.getAbilityState(ability); 521 console.info('getAbilityState ${state}'); 522}); 523``` 524 525### getCurrentTopAbility<sup>9+</sup> 526 527getCurrentTopAbility(callback: AsyncCallback\<UIAbility>): void 528 529Obtains the top ability of this application. This API uses an asynchronous callback to return the result. 530 531**System capability**: SystemCapability.Ability.AbilityRuntime.Core 532 533**Parameters** 534 535| Name | Type | Mandatory| Description | 536| -------- | ------------------------------------------------------------ | ---- | ------------------ | 537| callback | AsyncCallback\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Yes | Callback used to return the result.| 538 539**Error codes** 540 541| ID| Error Message| 542| ------- | -------- | 543| 16000100 | GetCurrentTopAbility failed. | 544 545For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 546 547**Example** 548 549```ts 550import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 551import UIAbility from '@ohos.app.ability.UIAbility'; 552import { BusinessError } from '@ohos.base'; 553 554let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 555let ability: UIAbility; 556 557abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 558abilityDelegator.getCurrentTopAbility((err : BusinessError, data : UIAbility) => { 559 console.info('getCurrentTopAbility callback'); 560 ability = data; 561}); 562``` 563 564### getCurrentTopAbility<sup>9+</sup> 565 566getCurrentTopAbility(): Promise\<UIAbility> 567 568Obtains the top ability of this application. This API uses a promise to return the result. 569 570**System capability**: SystemCapability.Ability.AbilityRuntime.Core 571 572**Return value** 573 574| Type | Description | 575| ----------------------------------------------------------- | -------------------------------------- | 576| Promise\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Promise used to return the top ability.| 577 578**Error codes** 579 580| ID| Error Message| 581| ------- | -------- | 582| 16000100 | GetCurrentTopAbility failed. | 583 584For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 585 586**Example** 587 588```ts 589import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 590import UIAbility from '@ohos.app.ability.UIAbility'; 591 592let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 593let ability: UIAbility; 594 595abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 596abilityDelegator.getCurrentTopAbility().then((data : UIAbility) => { 597 console.info('getCurrentTopAbility promise'); 598 ability = data; 599}); 600``` 601 602### startAbility<sup>9+</sup> 603 604startAbility(want: Want, callback: AsyncCallback\<void>): void 605 606Starts an ability. This API uses an asynchronous callback to return the result. 607 608**System capability**: SystemCapability.Ability.AbilityRuntime.Core 609 610**Parameters** 611 612| Name | Type | Mandatory| Description | 613| -------- | -------------------------------------- | ---- | ------------------ | 614| want | [Want](js-apis-app-ability-want.md) | Yes | **Want** parameter for starting the ability. | 615| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 616 617**Error codes** 618 619| ID| Error Message| 620| ------- | -------- | 621| 16000001 | The specified ability does not exist. | 622| 16000002 | Incorrect ability type. | 623| 16000004 | Can not start invisible component. | 624| 16000005 | The specified process does not have the permission. | 625| 16000006 | Cross-user operations are not allowed. | 626| 16000008 | The crowdtesting application expires. | 627| 16000009 | An ability cannot be started or stopped in Wukong mode. | 628| 16000010 | The call with the continuation flag is forbidden. | 629| 16000011 | The context does not exist. | 630| 16000012 | The application is controlled. | 631| 16000013 | The application is controlled by EDM. | 632| 16000050 | Internal error. | 633| 16000053 | The ability is not on the top of the UI. | 634| 16000055 | Installation-free timed out. | 635| 16200001 | The caller has been released. | 636 637For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 638 639**Example** 640 641```ts 642import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 643import Want from '@ohos.app.ability.Want'; 644import { BusinessError } from '@ohos.base'; 645 646let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 647let want: Want = { 648 bundleName: 'bundleName', 649 abilityName: 'abilityName' 650}; 651 652abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 653abilityDelegator.startAbility(want, (err : BusinessError, data : void) => { 654 console.info('startAbility callback'); 655}); 656``` 657 658### startAbility<sup>9+</sup> 659 660startAbility(want: Want): Promise\<void> 661 662Starts an ability. This API uses a promise to return the result. 663 664**System capability**: SystemCapability.Ability.AbilityRuntime.Core 665 666**Parameters** 667 668| Name| Type | Mandatory| Description | 669| ------ | -------------------------------------- | ---- | --------------- | 670| want | [Want](js-apis-app-ability-want.md) | Yes | **Want** parameter for starting the ability.| 671 672**Return value** 673 674| Type | Description | 675| -------------- | ------------------- | 676| Promise\<void> | Promise used to return the result.| 677 678**Error codes** 679 680| ID| Error Message| 681| ------- | -------- | 682| 16000001 | The specified ability does not exist. | 683| 16000002 | Incorrect ability type. | 684| 16000004 | Can not start invisible component. | 685| 16000005 | The specified process does not have the permission. | 686| 16000006 | Cross-user operations are not allowed. | 687| 16000008 | The crowdtesting application expires. | 688| 16000009 | An ability cannot be started or stopped in Wukong mode. | 689| 16000010 | The call with the continuation flag is forbidden. | 690| 16000011 | The context does not exist. | 691| 16000012 | The application is controlled. | 692| 16000013 | The application is controlled by EDM. | 693| 16000050 | Internal error. | 694| 16000053 | The ability is not on the top of the UI. | 695| 16000055 | Installation-free timed out. | 696| 16200001 | The caller has been released. | 697 698For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 699 700**Example** 701 702```ts 703import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 704import UIAbility from '@ohos.app.ability.UIAbility'; 705import Want from '@ohos.app.ability.Want'; 706 707let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 708let want: Want = { 709 bundleName: 'bundleName', 710 abilityName: 'abilityName' 711}; 712 713abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 714abilityDelegator.startAbility(want).then((data: void) => { 715 console.info('startAbility promise'); 716}); 717``` 718 719### doAbilityForeground<sup>9+</sup> 720 721doAbilityForeground(ability: UIAbility, callback: AsyncCallback\<void>): void 722 723Schedules the lifecycle state of an ability to **Foreground**. This API uses an asynchronous callback to return the result. 724 725**System capability**: SystemCapability.Ability.AbilityRuntime.Core 726 727**Parameters** 728 729| Name | Type | Mandatory| Description | 730| -------- | ----------------------- | ---- | ------------------------------------------------------- | 731| ability | UIAbility | Yes | Target ability. | 732| callback | AsyncCallback\<void> | Yes | Callback used to return the result. | 733 734**Error codes** 735 736| ID| Error Message| 737| ------- | -------- | 738| 16000100 | DoAbilityForeground failed. | 739 740For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 741 742**Example** 743 744```ts 745import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 746import UIAbility from '@ohos.app.ability.UIAbility'; 747import { BusinessError } from '@ohos.base'; 748 749let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 750let ability: UIAbility; 751 752abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 753abilityDelegator.getCurrentTopAbility((err : BusinessError, data : UIAbility) => { 754 console.info('getCurrentTopAbility callback'); 755 ability = data; 756 abilityDelegator.doAbilityForeground(ability, (err : BusinessError) => { 757 console.info("doAbilityForeground callback"); 758 }); 759}); 760``` 761 762### doAbilityForeground<sup>9+</sup> 763 764doAbilityForeground(ability: UIAbility): Promise\<void> 765 766Schedules the lifecycle state of an ability to **Foreground**. This API uses a promise to return the result. 767 768**System capability**: SystemCapability.Ability.AbilityRuntime.Core 769 770**Parameters** 771 772| Name | Type | Mandatory| Description | 773| ------- | ------- | ---- | --------------- | 774| ability | UIAbility | Yes | Target ability.| 775 776**Return value** 777 778| Type | Description | 779| ----------------- | ------------------------------------------------------------ | 780| Promise\<void> | Promise used to return the result. | 781 782**Error codes** 783 784| ID| Error Message| 785| ------- | -------- | 786| 16000100 | DoAbilityForeground failed. | 787 788For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 789 790**Example** 791 792```ts 793import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 794import UIAbility from '@ohos.app.ability.UIAbility'; 795import { BusinessError } from '@ohos.base'; 796 797let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 798let ability: UIAbility; 799 800abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 801abilityDelegator.getCurrentTopAbility((err : BusinessError, data : UIAbility) => { 802 console.info('getCurrentTopAbility callback'); 803 ability = data; 804 abilityDelegator.doAbilityForeground(ability).then(() => { 805 console.info("doAbilityForeground promise"); 806 }); 807}); 808``` 809 810### doAbilityBackground<sup>9+</sup> 811 812doAbilityBackground(ability: UIAbility, callback: AsyncCallback\<void>): void 813 814Schedules the lifecycle state of an ability to **Background**. This API uses an asynchronous callback to return the result. 815 816**System capability**: SystemCapability.Ability.AbilityRuntime.Core 817 818**Parameters** 819 820| Name | Type | Mandatory| Description | 821| -------- | ----------------------- | ---- | ------------------------------------------------------- | 822| ability | UIAbility | Yes | Target ability. | 823| callback | AsyncCallback\<void> | Yes | Callback used to return the result.<br>\- **true**: The operation is successful.<br>\- **false**: The operation failed.| 824 825**Error codes** 826 827| ID| Error Message| 828| ------- | -------- | 829| 16000100 | DoAbilityBackground failed. | 830 831For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 832 833**Example** 834 835```ts 836import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 837import UIAbility from '@ohos.app.ability.UIAbility'; 838import { BusinessError } from '@ohos.base'; 839 840let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 841let ability: UIAbility; 842 843abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 844abilityDelegator.getCurrentTopAbility((err : BusinessError, data : UIAbility) => { 845 console.info('getCurrentTopAbility callback'); 846 ability = data; 847 abilityDelegator.doAbilityBackground(ability, (err : BusinessError) => { 848 console.info("doAbilityBackground callback"); 849 }); 850}); 851``` 852 853### doAbilityBackground<sup>9+</sup> 854 855doAbilityBackground(ability: UIAbility): Promise\<void> 856 857Schedules the lifecycle state of an ability to **Background**. This API uses a promise to return the result. 858 859**System capability**: SystemCapability.Ability.AbilityRuntime.Core 860 861**Parameters** 862 863| Name | Type | Mandatory| Description | 864| ------- | ------- | ---- | --------------- | 865| ability | UIAbility | Yes | Target ability.| 866 867**Return value** 868 869| Type | Description | 870| ----------------- | ------------------------------------------------------------ | 871| Promise\<boolean> | Promise used to return the result.<br>\- **true**: The operation is successful.<br>\- **false**: The operation failed.| 872 873**Error codes** 874 875| ID| Error Message| 876| ------- | -------- | 877| 16000100 | DoAbilityBackground failed. | 878 879For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 880 881**Example** 882 883```ts 884import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 885import UIAbility from '@ohos.app.ability.UIAbility'; 886import { BusinessError } from '@ohos.base'; 887 888let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 889let ability: UIAbility; 890 891abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 892abilityDelegator.getCurrentTopAbility((err : BusinessError, data : UIAbility) => { 893 console.info('getCurrentTopAbility callback'); 894 ability = data; 895 abilityDelegator.doAbilityBackground(ability).then(() => { 896 console.info("doAbilityBackground promise"); 897 }); 898}); 899``` 900 901### printSync<sup>9+</sup> 902 903printSync(msg: string): void 904 905Prints log information to the unit test console. 906 907**System capability**: SystemCapability.Ability.AbilityRuntime.Core 908 909**Parameters** 910 911| Name| Type | Mandatory| Description | 912| ------ | ------ | ---- | ---------- | 913| msg | string | Yes | Log string.| 914 915**Example** 916 917```ts 918import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 919 920let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 921let msg = 'msg'; 922 923abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 924abilityDelegator.printSync(msg); 925``` 926 927### print 928 929print(msg: string, callback: AsyncCallback\<void>): void 930 931Prints log information to the unit test console. This API uses an asynchronous callback to return the result. 932 933**System capability**: SystemCapability.Ability.AbilityRuntime.Core 934 935**Parameters** 936 937| Name | Type | Mandatory| Description | 938| -------- | -------------------- | ---- | ------------------ | 939| msg | string | Yes | Log string. | 940| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 941 942**Example** 943 944```ts 945import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 946import { BusinessError } from '@ohos.base'; 947 948let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 949let msg = 'msg'; 950 951abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 952abilityDelegator.print(msg, (err : BusinessError) => { 953 console.info('print callback'); 954}); 955``` 956 957### print 958 959print(msg: string): Promise\<void> 960 961Prints log information to the unit test console. This API uses a promise to return the result. 962 963**System capability**: SystemCapability.Ability.AbilityRuntime.Core 964 965**Parameters** 966 967| Name| Type | Mandatory| Description | 968| ------ | ------ | ---- | ---------- | 969| msg | string | Yes | Log string.| 970 971**Return value** 972 973| Type | Description | 974| -------------- | ------------------- | 975| Promise\<void> | Promise used to return the result.| 976 977**Example** 978 979```ts 980import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 981 982let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 983let msg = 'msg'; 984 985abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 986abilityDelegator.print(msg).then(() => { 987 console.info('print promise'); 988}); 989``` 990 991### executeShellCommand 992 993executeShellCommand(cmd: string, callback: AsyncCallback\<ShellCmdResult>): void 994 995Executes a shell command. This API uses an asynchronous callback to return the result. 996 997Only the following shell commands are supported: aa, bm, cp, mkdir, rm, uinput, hilog, ppwd, echo, uitest, acm, hidumper, wukong, pkill, ps, and pidof. 998 999**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1000 1001**Parameters** 1002 1003| Name | Type | Mandatory| Description | 1004| -------- | ------------------------------------------------------------ | ---- | ------------------ | 1005| cmd | string | Yes | Shell command string. | 1006| callback | AsyncCallback\<[ShellCmdResult](js-apis-inner-application-shellCmdResult.md#ShellCmdResult)> | Yes | Callback used to return the result.| 1007 1008**Example** 1009 1010```ts 1011import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1012import { BusinessError } from '@ohos.base'; 1013 1014let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1015let cmd = 'cmd'; 1016 1017abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1018abilityDelegator.executeShellCommand(cmd, (err : BusinessError, data: AbilityDelegatorRegistry.ShellCmdResult) => { 1019 console.info('executeShellCommand callback'); 1020}); 1021``` 1022 1023### executeShellCommand 1024 1025executeShellCommand(cmd: string, timeoutSecs: number, callback: AsyncCallback\<ShellCmdResult>): void 1026 1027Executes a shell command with the timeout period specified. This API uses an asynchronous callback to return the result. 1028 1029Only the following shell commands are supported: aa, bm, cp, mkdir, rm, uinput, hilog, ppwd, echo, uitest, acm, hidumper, wukong, pkill, ps, and pidof. 1030 1031**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1032 1033**Parameters** 1034 1035| Name | Type | Mandatory| Description | 1036| ----------- | ------------------------------------------------------------ | ---- | ----------------------------- | 1037| cmd | string | Yes | Shell command string. | 1038| timeoutSecs | number | Yes | Command timeout period, in seconds.| 1039| callback | AsyncCallback\<[ShellCmdResult](js-apis-inner-application-shellCmdResult.md#ShellCmdResult)> | Yes | Callback used to return the result. | 1040 1041**Example** 1042 1043```ts 1044import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1045import { BusinessError } from '@ohos.base'; 1046 1047let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1048let cmd = 'cmd'; 1049let timeout = 100; 1050 1051abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1052abilityDelegator.executeShellCommand(cmd, timeout, (err : BusinessError, data: AbilityDelegatorRegistry.ShellCmdResult) => { 1053 console.info('executeShellCommand callback'); 1054}); 1055``` 1056 1057### executeShellCommand 1058 1059executeShellCommand(cmd: string, timeoutSecs?: number): Promise\<ShellCmdResult> 1060 1061Executes a shell command with the timeout period specified. This API uses a promise to return the result. 1062 1063Only the following shell commands are supported: aa, bm, cp, mkdir, rm, uinput, hilog, ppwd, echo, uitest, acm, hidumper, wukong, pkill, ps, and pidof. 1064 1065**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1066 1067**Parameters** 1068 1069| Name | Type | Mandatory| Description | 1070| ----------- | ------ | ---- | ----------------------------- | 1071| cmd | string | Yes | Shell command string. | 1072| timeoutSecs | number | No | Command timeout period, in seconds.| 1073 1074**Return value** 1075 1076| Type | Description | 1077| ------------------------------------------------------------ | ------------------------------------------------------------ | 1078| Promise\<[ShellCmdResult](js-apis-inner-application-shellCmdResult.md#ShellCmdResult)> | Promise used to return a [ShellCmdResult](js-apis-inner-application-shellCmdResult.md#ShellCmdResult) object.| 1079 1080**Example** 1081 1082```ts 1083import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1084 1085let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1086let cmd = 'cmd'; 1087let timeout = 100; 1088 1089abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1090abilityDelegator.executeShellCommand(cmd, timeout).then((data) => { 1091 console.info('executeShellCommand promise'); 1092}); 1093``` 1094 1095### finishTest<sup>9+</sup> 1096 1097finishTest(msg: string, code: number, callback: AsyncCallback\<void>): void 1098 1099Finishes the test and prints log information to the unit test console. This API uses an asynchronous callback to return the result. 1100 1101**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1102 1103**Parameters** 1104 1105| Name | Type | Mandatory| Description | 1106| -------- | -------------------- | ---- | ------------------ | 1107| msg | string | Yes | Log string. | 1108| code | number | Yes | Log code. | 1109| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 1110 1111**Error codes** 1112 1113| ID| Error Message| 1114| ------- | -------- | 1115| 16000100 | FinishTest failed. | 1116 1117For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1118 1119**Example** 1120 1121```ts 1122import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1123import { BusinessError } from '@ohos.base'; 1124 1125let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1126let msg = 'msg'; 1127 1128abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1129abilityDelegator.finishTest(msg, 0, (err : BusinessError) => { 1130 console.info('finishTest callback'); 1131}); 1132``` 1133 1134### finishTest<sup>9+</sup> 1135 1136finishTest(msg: string, code: number): Promise\<void> 1137 1138Finishes the test and prints log information to the unit test console. This API uses a promise to return the result. 1139 1140**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1141 1142**Parameters** 1143 1144| Name| Type | Mandatory| Description | 1145| ------ | ------ | ---- | ---------- | 1146| msg | string | Yes | Log string.| 1147| code | number | Yes | Log code. | 1148 1149**Return value** 1150 1151| Type | Description | 1152| -------------- | ------------------- | 1153| Promise\<void> | Promise used to return the result.| 1154 1155**Error codes** 1156 1157| ID| Error Message| 1158| ------- | -------- | 1159| 16000100 | FinishTest failed. | 1160 1161For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1162 1163**Example** 1164 1165```ts 1166import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1167 1168let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1169let msg = 'msg'; 1170 1171abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1172abilityDelegator.finishTest(msg, 0).then(() => { 1173 console.info('finishTest promise'); 1174}); 1175``` 1176 1177### addAbilityStageMonitor<sup>9+</sup> 1178 1179addAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback\<void>): void 1180 1181Adds an **AbilityStageMonitor** instance to monitor the lifecycle state changes of an ability stage. This API uses an asynchronous callback to return the result. 1182 1183**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1184 1185**Parameters** 1186 1187| Name | Type | Mandatory| Description | 1188| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1189| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1190| callback | AsyncCallback\<void> | Yes | Callback used to return the result. | 1191 1192**Error codes** 1193 1194| ID| Error Message| 1195| ------- | -------- | 1196| 16000100 | AddAbilityStageMonitor failed. | 1197 1198For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1199 1200**Example** 1201 1202```ts 1203import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1204import { BusinessError } from '@ohos.base'; 1205 1206let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1207 1208abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1209abilityDelegator.addAbilityStageMonitor({ 1210 moduleName: 'moduleName', 1211 srcEntrance: 'srcEntrance', 1212}, (err : BusinessError) => { 1213 console.info('addAbilityStageMonitor callback'); 1214}); 1215``` 1216 1217### addAbilityStageMonitor<sup>9+</sup> 1218 1219addAbilityStageMonitor(monitor: AbilityStageMonitor): Promise\<void> 1220 1221Adds an **AbilityStageMonitor** instance to monitor the lifecycle state changes of an ability stage. This API uses a promise to return the result. 1222 1223**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1224 1225**Parameters** 1226 1227| Name | Type | Mandatory| Description | 1228| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1229| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1230 1231**Return value** 1232 1233| Type | Description | 1234| -------------- | ------------------- | 1235| Promise\<void> | Promise used to return the result.| 1236 1237**Error codes** 1238 1239| ID| Error Message| 1240| ------- | -------- | 1241| 16000100 | AddAbilityStageMonitor failed. | 1242 1243For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1244 1245**Example** 1246 1247```ts 1248import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1249 1250let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1251 1252abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1253abilityDelegator.addAbilityStageMonitor({ 1254 moduleName: 'moduleName', 1255 srcEntrance: 'srcEntrance', 1256}).then(() => { 1257 console.info('addAbilityStageMonitor promise'); 1258}); 1259``` 1260 1261### addAbilityStageMonitorSync<sup>10+</sup> 1262 1263addAbilityStageMonitorSync(monitor: AbilityStageMonitor): void 1264 1265Adds an **AbilityStageMonitor** instance to monitor the lifecycle state changes of an ability stage. This API returns the result synchronously. 1266 1267**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1268 1269**Parameters** 1270 1271| Name | Type | Mandatory| Description | 1272| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1273| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1274 1275**Error codes** 1276 1277| ID| Error Message| 1278| ------- | -------- | 1279| 16000100 | AddAbilityStageMonitorSync failed. | 1280 1281For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1282 1283**Example** 1284 1285```ts 1286import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1287 1288let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1289 1290abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1291abilityDelegator.addAbilityStageMonitorSync({ 1292 moduleName: 'moduleName', 1293 srcEntrance: 'srcEntrance', 1294}); 1295``` 1296 1297### removeAbilityStageMonitor<sup>9+</sup> 1298 1299removeAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback\<void>): void 1300 1301Removes an **AbilityStageMonitor** instance from the application memory. This API uses an asynchronous callback to return the result. 1302 1303**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1304 1305**Parameters** 1306 1307| Name | Type | Mandatory| Description | 1308| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1309| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1310| callback | AsyncCallback\<void> | Yes | Callback used to return the result. | 1311 1312**Error codes** 1313 1314| ID| Error Message| 1315| ------- | -------- | 1316| 16000100 | RemoveAbilityStageMonitor failed. | 1317 1318For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1319 1320**Example** 1321 1322```ts 1323import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1324import { BusinessError } from '@ohos.base'; 1325 1326let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1327 1328abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1329abilityDelegator.removeAbilityStageMonitor({ 1330 moduleName: 'moduleName', 1331 srcEntrance: 'srcEntrance', 1332}, (err : BusinessError) => { 1333 console.info('removeAbilityStageMonitor callback'); 1334}); 1335``` 1336 1337### removeAbilityStageMonitor<sup>9+</sup> 1338 1339removeAbilityStageMonitor(monitor: AbilityStageMonitor): Promise\<void> 1340 1341Removes an **AbilityStageMonitor** instance from the application memory. This API uses a promise to return the result. 1342 1343**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1344 1345**Parameters** 1346 1347| Name | Type | Mandatory| Description | 1348| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1349| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1350 1351**Return value** 1352 1353| Type | Description | 1354| -------------- | ------------------- | 1355| Promise\<void> | Promise used to return the result.| 1356 1357**Error codes** 1358 1359| ID| Error Message| 1360| ------- | -------- | 1361| 16000100 | RemoveAbilityStageMonitor failed. | 1362 1363For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1364 1365**Example** 1366 1367```ts 1368import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1369 1370let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1371 1372abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1373abilityDelegator.removeAbilityStageMonitor({ 1374 moduleName: 'moduleName', 1375 srcEntrance: 'srcEntrance', 1376}).then(() => { 1377 console.info('removeAbilityStageMonitor promise'); 1378}); 1379``` 1380 1381### removeAbilityStageMonitorSync<sup>10+</sup> 1382 1383removeAbilityStageMonitorSync(monitor: AbilityStageMonitor): void 1384 1385Removes an **AbilityStageMonitor** instance from the application memory. This API returns the result synchronously. 1386 1387**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1388 1389**Parameters** 1390 1391| Name | Type | Mandatory| Description | 1392| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1393| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1394 1395**Error codes** 1396 1397| ID| Error Message| 1398| ------- | -------- | 1399| 16000100 | removeAbilityStageMonitorSync failed. | 1400 1401For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1402 1403**Example** 1404 1405```ts 1406import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1407 1408let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1409 1410abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1411abilityDelegator.removeAbilityStageMonitorSync({ 1412 moduleName: 'moduleName', 1413 srcEntrance: 'srcEntrance', 1414}); 1415``` 1416 1417### waitAbilityStageMonitor<sup>9+</sup> 1418 1419waitAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback\<AbilityStage>): void 1420 1421Waits for an **AbilityStage** instance that matches the conditions set in an **AbilityStageMonitor** instance and returns the **AbilityStage** instance. This API uses an asynchronous callback to return the result. 1422 1423**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1424 1425**Parameters** 1426 1427| Name | Type | Mandatory| Description | 1428| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1429| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1430| callback | AsyncCallback\<AbilityStage> | Yes | Callback used to return the result. If the operation is successful, an **AbilityStage** instance is returned. Otherwise, no value is returned. | 1431 1432**Error codes** 1433 1434| ID| Error Message| 1435| ------- | -------- | 1436| 16000100 | WaitAbilityStageMonitor failed. | 1437 1438For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1439 1440**Example** 1441 1442```ts 1443import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1444import AbilityStage from '@ohos.app.ability.AbilityStage'; 1445import { BusinessError } from '@ohos.base'; 1446 1447let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1448 1449abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1450abilityDelegator.waitAbilityStageMonitor({ 1451 moduleName: 'moduleName', 1452 srcEntrance: 'srcEntrance', 1453}, (err : BusinessError, data : AbilityStage) => { 1454 console.info('waitAbilityStageMonitor callback'); 1455}); 1456``` 1457 1458### waitAbilityStageMonitor<sup>9+</sup> 1459 1460waitAbilityStageMonitor(monitor: AbilityStageMonitor, timeout?: number): Promise\<AbilityStage> 1461 1462Waits for an **AbilityStage** instance that matches the conditions set in an **AbilityStageMonitor** instance and returns the **AbilityStage** instance. This API uses a promise to return the result. 1463 1464**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1465 1466**Parameters** 1467 1468| Name | Type | Mandatory| Description | 1469| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1470| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1471| timeout | number | No | Maximum waiting time, in milliseconds.| 1472 1473**Return value** 1474 1475| Type | Description | 1476| -------------- | ------------------- | 1477| Promise\<AbilityStage> | Promise used to return the result. If the operation is successful, an **AbilityStage** instance is returned. Otherwise, no value is returned.| 1478 1479**Error codes** 1480 1481| ID| Error Message| 1482| ------- | -------- | 1483| 16000100 | WaitAbilityStageMonitor failed. | 1484 1485For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1486 1487**Example** 1488 1489```ts 1490import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1491import AbilityStage from '@ohos.app.ability.AbilityStage'; 1492 1493let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1494 1495abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1496abilityDelegator.waitAbilityStageMonitor({ 1497 moduleName: 'moduleName', 1498 srcEntrance: 'srcEntrance', 1499}).then((data : AbilityStage) => { 1500 console.info('waitAbilityStageMonitor promise'); 1501}); 1502``` 1503 1504### waitAbilityStageMonitor<sup>9+</sup> 1505 1506waitAbilityStageMonitor(monitor: AbilityStageMonitor, timeout: number, callback: AsyncCallback\<AbilityStage>): void 1507 1508Waits for an **AbilityStage** instance that matches the conditions set in an **AbilityStageMonitor** instance and returns the **AbilityStage** instance. This API uses an asynchronous callback to return the result. 1509 1510**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1511 1512**Parameters** 1513 1514| Name | Type | Mandatory| Description | 1515| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1516| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1517| timeout | number | Yes | Maximum waiting time, in milliseconds.| 1518| callback | AsyncCallback\<AbilityStage> | Yes | Callback used to return the result. If the operation is successful, an **AbilityStage** instance is returned. Otherwise, no value is returned. | 1519 1520**Error codes** 1521 1522| ID| Error Message| 1523| ------- | -------- | 1524| 16000100 | WaitAbilityStageMonitor failed. | 1525 1526For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1527 1528**Example** 1529 1530```ts 1531import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1532import AbilityStage from '@ohos.app.ability.AbilityStage'; 1533import { BusinessError } from '@ohos.base'; 1534 1535let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1536let timeout = 100; 1537 1538abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1539abilityDelegator.waitAbilityStageMonitor({ 1540 moduleName: 'moduleName', 1541 srcEntrance: 'srcEntrance', 1542}, timeout, (err : BusinessError, data : AbilityStage) => { 1543 console.info('waitAbilityStageMonitor callback'); 1544}); 1545``` 1546 1547### setMockList<sup>11+</sup> 1548 1549setMockList(mockList: Record\<string, string>): void 1550 1551Sets a list of mock data. 1552 1553**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1554 1555**Parameters** 1556 1557| Name | Type | Mandatory| Description | 1558| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 1559| mockList | Record\<string, string> | Yes | Key-value object of the mock, where **key** is the target path to be replaced and **value** is the path of the mock implementation to be used for the replacement.| 1560 1561**Error codes** 1562 1563| ID| Error Message | 1564| -------- | --------------- | 1565| 16000050 | Internal error. | 1566 1567For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1568 1569**Example** 1570 1571```ts 1572import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1573 1574let mockList: Record<string, string> = { 1575 '@ohos.router': 'src/main/mock/ohos/router.mock', 1576 'common.time': 'src/main/mock/common/time.mock', 1577}; 1578let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1579abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1580abilityDelegator.setMockList(mockList); 1581``` 1582