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