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