1# @ohos.app.ability.abilityManager (AbilityManager)(系统接口) 2 3AbilityManager模块提供获取、新增、修改Ability相关信息和运行状态信息的能力。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 本模块接口均为系统接口，三方应用不支持调用。 9 10## 导入模块 11 12```ts 13import { abilityManager } from '@kit.AbilityKit'; 14``` 15 16## UserStatus<sup>12+</sup> 17 18用户操作的断言调试结果，该类型为枚举。 19 20**系统接口**：该接口为系统接口。 21 22**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 23 24| 名称 | 值 | 说明 | 25| -------- | -------- | -------- | 26| ASSERT_TERMINATE | 0 | 表示用户点击终止的操作的断言调试结果。 | 27| ASSERT_CONTINUE | 1 | 表示用户点击继续的操作的断言调试结果。 | 28| ASSERT_RETRY | 2 | 表示用户点击重试的操作的断言调试结果。 | 29 30## updateConfiguration 31 32updateConfiguration(config: Configuration, callback: AsyncCallback\<void>): void 33 34通过传入修改的配置项来更新配置（callback形式）。 35 36**系统接口**：此接口为系统接口。 37 38**需要权限**：ohos.permission.UPDATE_CONFIGURATION 39 40**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 41 42**参数**： 43 44| 参数名 | 类型 | 必填 | 说明 | 45| --------- | ---------------------------------------- | ---- | -------------- | 46| config | [Configuration](js-apis-app-ability-configuration.md) | 是 | 新的配置项，仅需配置需要更新的项。 | 47| callback | AsyncCallback\<void> | 是 | 以回调方式返回接口运行结果，可进行错误处理或其他自定义处理。 | 48 49**错误码**： 50 51以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 52 53| 错误码ID | 错误信息 | 54| ------- | -------- | 55| 201 | Permission denied. | 56| 202 | Not System App. Interface caller is not a system app. | 57| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 58| 16000050 | Internal error. | 59 60**示例**： 61 62```ts 63import { abilityManager, Configuration, ConfigurationConstant } from '@kit.AbilityKit'; 64import { BusinessError } from '@kit.BasicServicesKit'; 65 66const config: Configuration = { 67 language: 'Zh-Hans', // 简体中文 68 colorMode: ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT, // 浅色模式 69 direction: ConfigurationConstant.Direction.DIRECTION_VERTICAL, // 垂直方向 70 screenDensity: ConfigurationConstant.ScreenDensity.SCREEN_DENSITY_SDPI, // 屏幕像素密度为'sdpi' 71 displayId: 1, // 应用在Id为1的物理屏上显示 72 hasPointerDevice: true, // 指针类型设备已连接 73}; 74 75try { 76 abilityManager.updateConfiguration(config, (err: BusinessError) => { 77 if (err) { 78 console.error(`updateConfiguration fail, err: ${JSON.stringify(err)}`); 79 } else { 80 console.log('updateConfiguration success.'); 81 } 82 }); 83} catch (paramError) { 84 let code: number = (paramError as BusinessError).code; 85 let message: string = (paramError as BusinessError).message; 86 console.error(`error.code: ${code}, error.message: ${message}`); 87} 88``` 89 90## updateConfiguration 91 92updateConfiguration(config: Configuration): Promise\<void> 93 94通过修改配置来更新配置（Promise形式）。 95 96**系统接口**：此接口为系统接口。 97 98**需要权限**：ohos.permission.UPDATE_CONFIGURATION 99 100**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 101 102**参数**： 103 104| 参数名 | 类型 | 必填 | 说明 | 105| --------- | ---------------------------------------- | ---- | -------------- | 106| config | [Configuration](js-apis-app-ability-configuration.md) | 是 | 新的配置项，仅需配置需要更新的项。 | 107 108**返回值：** 109 110| 类型 | 说明 | 111| ---------------------------------------- | ------- | 112| Promise\<void> | 以Promise方式返回接口运行结果息，可进行错误处理或其他自定义处理。 | 113 114**错误码**： 115 116以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 117 118| 错误码ID | 错误信息 | 119| ------- | -------- | 120| 201 | Permission denied. | 121| 202 | Not System App. Interface caller is not a system app. | 122| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 123| 16000050 | Internal error. | 124 125**示例**： 126 127```ts 128import { abilityManager, Configuration, ConfigurationConstant } from '@kit.AbilityKit'; 129import { BusinessError } from '@kit.BasicServicesKit';; 130 131const config: Configuration = { 132 language: 'Zh-Hans', // 简体中文 133 colorMode: ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT, // 浅色模式 134 direction: ConfigurationConstant.Direction.DIRECTION_VERTICAL, // 垂直方向 135 screenDensity: ConfigurationConstant.ScreenDensity.SCREEN_DENSITY_SDPI, // 屏幕像素密度为'sdpi' 136 displayId: 1, // 应用在Id为1的物理屏上显示 137 hasPointerDevice: true, // 指针类型设备已连接 138}; 139 140try { 141 abilityManager.updateConfiguration(config).then(() => { 142 console.log('updateConfiguration success.'); 143 }).catch((err: BusinessError) => { 144 console.error(`updateConfiguration fail, err: ${JSON.stringify(err)}`); 145 }); 146} catch (paramError) { 147 let code: number = (paramError as BusinessError).code; 148 let message: string = (paramError as BusinessError).message; 149 console.error(`error.code: ${code}, error.message: ${message}`); 150} 151``` 152 153## getAbilityRunningInfos 154 155getAbilityRunningInfos(callback: AsyncCallback\<Array\<AbilityRunningInfo>>): void 156 157获取UIAbility运行相关信息（callback形式）。 158 159**系统接口**：此接口为系统接口。 160 161**需要权限**：ohos.permission.GET_RUNNING_INFO 162 163**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 164 165**参数**： 166 167| 参数名 | 类型 | 必填 | 说明 | 168| --------- | ---------------------------------------- | ---- | -------------- | 169| callback | AsyncCallback\<Array\<[AbilityRunningInfo](js-apis-inner-application-abilityRunningInfo.md)>> | 是 | 以回调方式返回接口运行结果及运行中的ability信息，可进行错误处理或其他自定义处理。 | 170 171**错误码**： 172 173以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 174 175| 错误码ID | 错误信息 | 176| ------- | -------- | 177| 202 | Not System App. Interface caller is not a system app. | 178| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 179| 16000050 | Internal error. | 180 181**示例**： 182 183```ts 184import { abilityManager } from '@kit.AbilityKit'; 185import { BusinessError } from '@kit.BasicServicesKit'; 186 187try { 188 abilityManager.getAbilityRunningInfos((err: BusinessError, data: Array<abilityManager.AbilityRunningInfo>) => { 189 if (err) { 190 console.error(`getAbilityRunningInfos fail, error: ${JSON.stringify(err)}`); 191 } else { 192 console.log(`getAbilityRunningInfos success, data: ${JSON.stringify(data)}`); 193 } 194 }); 195} catch (paramError) { 196 let code: number = (paramError as BusinessError).code; 197 let message: string = (paramError as BusinessError).message; 198 console.error(`error.code: ${code}, error.message: ${message}`); 199} 200``` 201 202## getExtensionRunningInfos 203 204getExtensionRunningInfos(upperLimit: number, callback: AsyncCallback\<Array\<ExtensionRunningInfo>>): void 205 206获取关于运行扩展能力的信息（callback形式）。 207 208**系统接口**：此接口为系统接口。 209 210**需要权限**：ohos.permission.GET_RUNNING_INFO 211 212**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 213 214**参数**： 215 216| 参数名 | 类型 | 必填 | 说明 | 217| --------- | ---------------------------------------- | ---- | -------------- | 218| upperLimit | number | 是 | 获取消息数量的最大限制，最大为2<sup>31</sup>-1。 | 219| callback | AsyncCallback\<Array\<[ExtensionRunningInfo](js-apis-inner-application-extensionRunningInfo-sys.md)>> | 是 | 以回调方式返回接口运行结果及运行中的extension信息，可进行错误处理或其他自定义处理。 | 220 221**错误码**： 222 223以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 224 225| 错误码ID | 错误信息 | 226| ------- | -------- | 227| 202 | Not System App. Interface caller is not a system app. | 228| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 229| 16000050 | Internal error. | 230 231**示例**： 232 233```ts 234import { abilityManager } from '@kit.AbilityKit'; 235import { BusinessError } from '@kit.BasicServicesKit'; 236 237let upperLimit = 10; 238 239try { 240 abilityManager.getExtensionRunningInfos(upperLimit, (err: BusinessError, data: Array<abilityManager.ExtensionRunningInfo>) => { 241 if (err) { 242 console.error(`getExtensionRunningInfos fail, err: ${JSON.stringify(err)}`); 243 } else { 244 console.log(`getExtensionRunningInfos success, data: ${JSON.stringify(data)}`); 245 } 246 }); 247} catch (paramError) { 248 let code: number = (paramError as BusinessError).code; 249 let message: string = (paramError as BusinessError).message; 250 console.error(`error.code: ${code}, error.message: ${message}`); 251} 252``` 253 254## getExtensionRunningInfos 255 256getExtensionRunningInfos(upperLimit: number): Promise\<Array\<ExtensionRunningInfo>> 257 258获取关于运行扩展能力的信息（Promise形式）。 259 260**系统接口**：此接口为系统接口。 261 262**需要权限**：ohos.permission.GET_RUNNING_INFO 263 264**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 265 266**参数**： 267 268| 参数名 | 类型 | 必填 | 说明 | 269| --------- | ---------------------------------------- | ---- | -------------- | 270| upperLimit | number | 是 | 获取消息数量的最大限制，最大为2<sup>31</sup>-1。 | 271 272**返回值：** 273 274| 类型 | 说明 | 275| ---------------------------------------- | ------- | 276| Promise\<Array\<[ExtensionRunningInfo](js-apis-inner-application-extensionRunningInfo-sys.md)>> | 以Promise方式返回接口运行结果及运行中的extension信息，可进行错误处理或其他自定义处理。 | 277 278**错误码**： 279 280以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 281 282| 错误码ID | 错误信息 | 283| ------- | -------- | 284| 202 | Not System App. Interface caller is not a system app. | 285| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 286| 16000050 | Internal error. | 287 288**示例**： 289 290```ts 291import { abilityManager } from '@kit.AbilityKit'; 292import { BusinessError } from '@kit.BasicServicesKit'; 293 294let upperLimit = 10; 295 296try { 297 abilityManager.getExtensionRunningInfos(upperLimit).then((data: Array<abilityManager.ExtensionRunningInfo>) => { 298 console.log(`getExtensionRunningInfos success, data: ${JSON.stringify(data)}`); 299 }).catch((err: BusinessError) => { 300 console.error(`getExtensionRunningInfos fail, err: ${JSON.stringify(err)}`); 301 }); 302} catch (paramError) { 303 let code: number = (paramError as BusinessError).code; 304 let message: string = (paramError as BusinessError).message; 305 console.error(`error.code: ${code}, error.message: ${message}`); 306} 307``` 308 309## getTopAbility 310 311getTopAbility(callback: AsyncCallback\<ElementName>): void 312 313获取窗口焦点的ability接口（callback形式）。 314 315**系统接口**：此接口为系统接口。 316 317**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 318 319**参数**： 320 321| 参数名 | 类型 | 必填 | 说明 | 322| --------- | ---------------------------------------- | ---- | -------------- | 323| callback | AsyncCallback\<[ElementName](js-apis-bundleManager-elementName.md)> | 是 | 以回调方式返回接口运行结果及应用名，可进行错误处理或其他自定义处理。 | 324 325**错误码**： 326 327以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 328 329| 错误码ID | 错误信息 | 330| ------- | -------- | 331| 202 | Not System App. Interface caller is not a system app. | 332| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 333| 16000050 | Internal error. | 334 335**示例**： 336 337```ts 338import { abilityManager } from '@kit.AbilityKit'; 339import { BusinessError } from '@kit.BasicServicesKit'; 340 341abilityManager.getTopAbility((err: BusinessError, data) => { 342 if (err) { 343 console.error(`getTopAbility fail, err: ${JSON.stringify(err)}`); 344 } else { 345 console.log(`getTopAbility success, data: ${JSON.stringify(data)}`); 346 } 347}); 348``` 349 350## getTopAbility 351 352getTopAbility(): Promise\<ElementName> 353 354获取窗口焦点的ability接口（Promise形式）。 355 356**系统接口**：此接口为系统接口。 357 358**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 359 360**返回值：** 361 362| 类型 | 说明 | 363| ---------------------------------------- | ------- | 364| Promise\<[ElementName](js-apis-bundleManager-elementName.md)>| 以Promise方式返回接口运行结果及应用名，可进行错误处理或其他自定义处理。 | 365 366**错误码**： 367 368以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 369 370| 错误码ID | 错误信息 | 371| ------- | -------- | 372| 202 | Not System App. Interface caller is not a system app. | 373| 16000050 | Internal error. | 374 375**示例**： 376 377```ts 378import { abilityManager } from '@kit.AbilityKit'; 379import { BusinessError } from '@kit.BasicServicesKit'; 380 381abilityManager.getTopAbility().then((data) => { 382 console.log(`getTopAbility success, data: ${JSON.stringify(data)}`); 383}).catch((err: BusinessError) => { 384 console.error(`getTopAbility fail, err: ${JSON.stringify(err)}`); 385}); 386``` 387 388## acquireShareData<sup>10+</sup> 389 390acquireShareData(missionId: number, callback: AsyncCallback\<Record\<string, Object>>): void 391 392系统弹框通过该接口发起原子化服务分享，调用到目标UIAbility的onShare，返回分享数据（callback形式）。 393 394**系统接口**：此接口为系统接口。 395 396**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 397 398**参数**： 399 400| 参数名 | 类型 | 必填 | 说明 | 401| --------- | ---------------------------------------- | ---- | -------------- | 402| missionId | number | 是 | 目标应用的missionId，最大为2<sup>31</sup>-1。 | 403| callback | AsyncCallback\<Record\<string, Object>> | 是 | 以回调方式返回接口运行结果及分享得到的数据，可进行错误处理或其他自定义处理。 | 404 405**错误码**： 406 407以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 408 409| 错误码ID | 错误信息 | 410| ------- | -------- | 411| 202 | Not System App. Interface caller is not a system app. | 412| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 413| 16000050 | Internal error. | 414 415**示例**： 416 417```ts 418import { abilityManager } from '@kit.AbilityKit'; 419import { BusinessError } from '@kit.BasicServicesKit'; 420 421try { 422 abilityManager.acquireShareData(1, (err: BusinessError, wantParam: Record<string, Object>) => { 423 if (err) { 424 console.error(`acquireShareData fail, err: ${JSON.stringify(err)}`); 425 } else { 426 console.log(`acquireShareData success, data: ${JSON.stringify(wantParam)}`); 427 } 428 }); 429} catch (paramError) { 430 let code: number = (paramError as BusinessError).code; 431 let message: string = (paramError as BusinessError).message; 432 console.error(`error.code: ${code}, error.message: ${message}`); 433} 434``` 435 436## acquireShareData<sup>10+</sup> 437 438acquireShareData(missionId: number): Promise\<Record\<string, Object>> 439 440系统弹框通过该接口发起原子化服务分享，调用到目标UIAbility的onShare，返回分享数据（Promise形式）。 441 442**系统接口**：此接口为系统接口。 443 444**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 445 446**参数**： 447 448| 参数名 | 类型 | 必填 | 说明 | 449| --------- | ---------------------------------------- | ---- | -------------- | 450| missionId | number | 是 | 目标应用的missionId，最大为2<sup>31</sup>-1。 | 451 452**返回值：** 453 454| 类型 | 说明 | 455| ---------------------------------------- | ------- | 456| Promise\<Record\<string, Object>>| 以Promise方式返回接口运行结果及分享数据，可进行错误处理或其他自定义处理。 | 457 458**错误码**： 459 460以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 461 462| 错误码ID | 错误信息 | 463| ------- | -------- | 464| 202 | Not System App. Interface caller is not a system app. | 465| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 466| 16000050 | Internal error. | 467 468**示例**： 469 470```ts 471import { abilityManager } from '@kit.AbilityKit'; 472import { BusinessError } from '@kit.BasicServicesKit'; 473 474try { 475 abilityManager.acquireShareData(1).then((wantParam: Record<string, Object>) => { 476 console.log(`acquireShareData success, data: ${JSON.stringify(wantParam)}`); 477 }).catch((err: BusinessError) => { 478 console.error(`acquireShareData fail, err: ${JSON.stringify(err)}`); 479 }); 480} catch (paramError) { 481 let code: number = (paramError as BusinessError).code; 482 let message: string = (paramError as BusinessError).message; 483 console.error(`error.code: ${code}, error.message: ${message}`); 484} 485``` 486 487## notifySaveAsResult<sup>10+</sup> 488 489notifySaveAsResult(parameter: AbilityResult, requestCode: number, callback: AsyncCallback\<void>): void 490 491该接口仅供[DLP](../apis-data-protection-kit/js-apis-dlppermission.md)（Data Loss Prevention, 数据丢失防护）管理应用使用，其他应用禁止使用，DLP管理应用通过该接口通知沙箱应用另存为结果。使用callback异步回调。 492 493**模型约束**：此接口仅可在Stage模型下使用。 494 495**系统接口**：此接口为系统接口。 496 497**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 498 499**参数**： 500 501| 参数名 | 类型 | 必填 | 说明 | 502| --------- | ---------------------------------------- | ---- | -------------- | 503| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | 是 | 返回给调用startAbilityForResult 接口调用方的相关信息。 | 504| requestCode | number | 是 | DLP管理应用传入的请求代码。 | 505| callback | AsyncCallback<void\> | 是 | 回调函数。当另存为结果通知成功，err为undefined，否则为错误对象。 | 506 507**错误码**： 508 509以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 510 511| 错误码ID | 错误信息 | 512| ------- | -------- | 513| 201 | Permission denied. | 514| 202 | Not System App. Interface caller is not a system app. | 515| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 516| 16000050 | Internal error. | 517 518**示例**： 519 520```ts 521import { abilityManager, Want, common } from '@kit.AbilityKit'; 522import { BusinessError } from '@kit.BasicServicesKit'; 523 524let want: Want = { 525 bundleName: 'com.example.myapplication', 526 abilityName: 'EntryAbility' 527}; 528let resultCode = 100; 529// 返回给另存为行为发起方AbilityResult信息 530let abilityResult: common.AbilityResult = { 531 want, 532 resultCode 533}; 534let requestCode = 1; 535try { 536 abilityManager.notifySaveAsResult(abilityResult, requestCode, (err: BusinessError) => { 537 if (err && err.code != 0) { 538 console.error(`notifySaveAsResult fail, err: ${JSON.stringify(err)}`); 539 } else { 540 console.log(`notifySaveAsResult success`); 541 } 542 }); 543} catch (paramError) { 544 let code: number = (paramError as BusinessError).code; 545 let message: string = (paramError as BusinessError).message; 546 console.error(`error.code: ${code}, error.message: ${message}`); 547} 548``` 549 550## notifySaveAsResult<sup>10+</sup> 551 552notifySaveAsResult(parameter: AbilityResult, requestCode: number): Promise\<void> 553 554该接口仅供[DLP](../apis-data-protection-kit/js-apis-dlppermission.md)（Data Loss Prevention, 数据丢失防护）管理应用使用，其他应用禁止使用，DLP管理应用通过该接口通知沙箱应用另存为结果。使用Promise异步回调。 555 556**模型约束**：此接口仅可在Stage模型下使用。 557 558**系统接口**：此接口为系统接口。 559 560**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 561 562**参数**： 563 564| 参数名 | 类型 | 必填 | 说明 | 565| --------- | ---------------------------------------- | ---- | -------------- | 566| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | 是 | 返回给调用startAbilityForResult 接口调用方的相关信息。 | 567| requestCode | number | 是 | DLP管理应用传入的请求代码。 | 568 569**返回值：** 570 571| 类型 | 说明 | 572| ---------------------------------------- | ------- | 573| Promise<void\>| Promise对象。无返回结果的Promise对象。 | 574 575**错误码**： 576 577以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 578 579| 错误码ID | 错误信息 | 580| ------- | -------- | 581| 201 | Permission denied. | 582| 202 | Not System App. Interface caller is not a system app. | 583| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 584| 16000050 | Internal error. | 585 586**示例**： 587 588```ts 589import { abilityManager, Want, common } from '@kit.AbilityKit'; 590import { BusinessError } from '@kit.BasicServicesKit'; 591 592let want: Want = { 593 bundleName: 'com.example.myapplication', 594 abilityName: 'EntryAbility' 595}; 596let resultCode = 100; 597// 返回给另存为行为发起方AbilityResult信息 598let abilityResult: common.AbilityResult = { 599 want, 600 resultCode 601}; 602let requestCode = 1; 603try { 604 abilityManager.notifySaveAsResult(abilityResult, requestCode).then(() => { 605 console.log(`notifySaveAsResult success`); 606 }).catch((err: BusinessError) => { 607 console.error(`notifySaveAsResult fail, err: ${JSON.stringify(err)}`); 608 }); 609} catch (paramError) { 610 let code: number = (paramError as BusinessError).code; 611 let message: string = (paramError as BusinessError).message; 612 console.error(`error.code: ${code}, error.message: ${message}`); 613} 614``` 615 616## abilityManager.on('abilityForegroundState')<sup>11+</sup> 617 618on(type: 'abilityForegroundState', observer: AbilityForegroundStateObserver): void 619 620注册Ability的启动和退出的观测器。 621 622**系统接口**：此接口为系统接口。 623 624**需要权限**：ohos.permission.RUNNING_STATE_OBSERVER 625 626**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 627 628**参数：** 629 630| 参数名 | 类型 | 必填 | 说明 | 631| -------- | -------- | -------- | -------- | 632| type | string | 是 | 调用接口类型，固定填'abilityForegroundState'字符串。 | 633| observer | [AbilityForegroundStateObserver](js-apis-inner-application-abilityForegroundStateObserver-sys) | 是 | Ability状态观测器，用于观测Ability的启动和退出。 | 634 635**错误码**： 636 637以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 638 639| 错误码ID | 错误信息 | 640| ------- | -------- | 641| 201 | Permission denied. | 642| 202 | Not System App. Interface caller is not a system app. | 643| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 644| 16000050 | Internal error. | 645 646**示例：** 647 648```ts 649import { abilityManager } from '@kit.AbilityKit'; 650import { BusinessError } from '@kit.BasicServicesKit'; 651 652let observer: abilityManager.AbilityForegroundStateObserver = { 653 onAbilityStateChanged(abilityStateData) { 654 console.log(`onAbilityStateChanged: ${JSON.stringify(abilityStateData)}`); 655 }, 656}; 657try { 658 abilityManager.on('abilityForegroundState', observer); 659} catch (paramError) { 660 let code = (paramError as BusinessError).code; 661 let message = (paramError as BusinessError).message; 662 console.error(`error: ${code}, ${message} `); 663} 664``` 665 666## abilityManager.off('abilityForegroundState')<sup>11+</sup> 667 668off(type: 'abilityForegroundState', observer?: AbilityForegroundStateObserver): void 669 670取消注册Ability启动和退出的观测器。 671 672**系统接口**：此接口为系统接口。 673 674**需要权限**：ohos.permission.RUNNING_STATE_OBSERVER 675 676**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 677 678**参数：** 679 680| 参数名 | 类型 | 必填 | 说明 | 681| -------- | -------- | -------- | -------- | 682| type | string | 是 | 调用接口类型，固定填'abilityForegroundState'字符串。 | 683| observer | [AbilityForegroundStateObserver](js-apis-inner-application-abilityForegroundStateObserver-sys) | 否 | Ability状态观测器，用于观测Ability的启动和退出。如果未配置该参数，则取消当前应用注册的所有observer。如果配置了该参数，则取消该observer。 | 684 685**错误码**： 686 687以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 688 689| 错误码ID | 错误信息 | 690| ------- | -------- | 691| 201 | Permission denied. | 692| 202 | Not System App. Interface caller is not a system app. | 693| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 694| 16000050 | Internal error. | 695 696**示例：** 697 698```ts 699import { abilityManager } from '@kit.AbilityKit'; 700import { BusinessError } from '@kit.BasicServicesKit'; 701 702let observer_: abilityManager.AbilityForegroundStateObserver | undefined; 703// 1.注册应用启动和退出的监听器 704let observer: abilityManager.AbilityForegroundStateObserver = { 705 onAbilityStateChanged(abilityStateData: abilityManager.AbilityStateData) { 706 console.log(`onAbilityStateChanged: ${JSON.stringify(abilityStateData)}`); 707 }, 708}; 709try { 710 abilityManager.on('abilityForegroundState', observer); 711 observer_ = observer; 712} catch (paramError) { 713 let code = (paramError as BusinessError).code; 714 let message = (paramError as BusinessError).message; 715 console.error(`error: ${code}, ${message} `); 716} 717 718// 2.注销监听器 719try { 720 abilityManager.off('abilityForegroundState', observer_); 721} catch (paramError) { 722 let code = (paramError as BusinessError).code; 723 let message = (paramError as BusinessError).message; 724 console.error(`error: ${code}, ${message} `); 725} 726``` 727 728## abilityManager.getForegroundUIAbilities<sup>11+</sup> 729 730getForegroundUIAbilities(callback: AsyncCallback\<Array\<AbilityStateData>>): void 731 732获取前台正在运行的应用Ability的信息。 733 734**系统接口**：此接口为系统接口。 735 736**需要权限**：ohos.permission.GET_RUNNING_INFO 737 738**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 739 740**参数：** 741 742 | 参数名 | 类型 | 必填 | 说明 | 743 | -------- | -------- | -------- | -------- | 744 | callback | AsyncCallback\<Array\<[AbilityStateData](js-apis-inner-application-abilityStateData.md)>> | 是 |以回调方式返回接口运行结果及有关前台Ability的信息，可进行错误处理或其他自定义处理。 | 745 746**错误码**： 747 748以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 749 750| 错误码ID | 错误信息 | 751| ------- | -------- | 752| 201 | Permission denied. | 753| 202 | Not System App. Interface caller is not a system app. | 754| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 755| 16000050 | Internal error. | 756 757**示例：** 758 759```ts 760import { abilityManager } from '@kit.AbilityKit'; 761import { BusinessError } from '@kit.BasicServicesKit'; 762 763abilityManager.getForegroundUIAbilities((err: BusinessError, data: Array<abilityManager.AbilityStateData>) => { 764 if (err) { 765 console.error(`Get foreground ui abilities failed, error: ${JSON.stringify(err)}`); 766 } else { 767 console.log(`Get foreground ui abilities data is: ${JSON.stringify(data)}`); 768 } 769}); 770``` 771 772## abilityManager.getForegroundUIAbilities<sup>11+</sup> 773 774getForegroundUIAbilities(): Promise\<Array\<AbilityStateData>> 775 776获取前台正在运行的应用Ability的信息。 777 778**系统接口**：此接口为系统接口。 779 780**需要权限**：ohos.permission.GET_RUNNING_INFO 781 782**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 783 784**返回值：** 785 786| 类型 | 说明 | 787| -------- | -------- | 788| Promise\<Array\<[AbilityStateData](js-apis-inner-application-abilityStateData.md)>> | 以Promise方式返回接口运行结果及有关前台Ability的信息，可进行错误处理或其他自定义处理。| 789 790**错误码**： 791 792以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 793 794| 错误码ID | 错误信息 | 795| ------- | -------- | 796| 201 | Permission denied. | 797| 202 | Not System App. Interface caller is not a system app. | 798| 16000050 | Internal error. | 799 800**示例：** 801 802```ts 803import { abilityManager } from '@kit.AbilityKit'; 804import { BusinessError } from '@kit.BasicServicesKit'; 805 806abilityManager.getForegroundUIAbilities().then((data: Array<abilityManager.AbilityStateData>) => { 807 console.log(`Get foreground ui abilities data is: ${JSON.stringify(data)}`); 808}).catch((error: BusinessError) => { 809 console.error(`Get foreground ui abilities failed, error: ${JSON.stringify(error)}`); 810}); 811``` 812 813## abilityManager.notifyDebugAssertResult<sup>12+</sup> 814 815notifyDebugAssertResult(sessionId: string, status: UserStatus): Promise\<void> 816 817将断言调试结果通知应用程序。使用Promise异步回调。 818 819**系统接口**：此接口为系统接口。 820 821**需要权限**：ohos.permission.NOTIFY_DEBUG_ASSERT_RESULT 822 823**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 824 825**参数**： 826 827| 参数名 | 类型 | 必填 | 说明 | 828| ------- | -------- | -------- | -------- | 829| sessionId | string | 是 | 指示AssertFault的请求ID。 | 830| status | [UserStatus](#userstatus12) | 是 | 用户的操作状态。 | 831 832**返回值：** 833 834| 类型 | 说明 | 835| -------- | -------- | 836| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 837 838**错误码**： 839 840以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 841 842| 错误码ID | 错误信息 | 843| ------- | -------- | 844| 201 | Permission denied. | 845| 202 | Not System App. Interface caller is not a system app. | 846| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 847| 16000050 | Internal error. | 848 849**示例：** 850 851```ts 852import { abilityManager, UIExtensionAbility, wantConstant, Want, UIExtensionContentSession } from '@kit.AbilityKit'; 853import { BusinessError } from '@kit.BasicServicesKit'; 854 855export default class UiExtAbility extends UIExtensionAbility { 856 onSessionCreate(want: Want, session: UIExtensionContentSession): void { 857 let sessionId: string = ''; 858 if (want.parameters) { 859 sessionId = want.parameters[wantConstant.Params.ASSERT_FAULT_SESSION_ID] as string; 860 } 861 let status = abilityManager.UserStatus.ASSERT_TERMINATE; 862 abilityManager.notifyDebugAssertResult(sessionId, status).then(() => { 863 console.log('notifyDebugAssertResult success.'); 864 }).catch((err: BusinessError) => { 865 console.error(`notifyDebugAssertResult failed, error: ${JSON.stringify(err)}`); 866 }); 867 } 868} 869``` 870 871## abilityManager.isEmbeddedOpenAllowed<sup>12</sup> 872 873isEmbeddedOpenAllowed(context: Context, appId: string): Promise\<boolean> 874 875判断是否允许嵌入式拉起[EmbeddableUIAbility](js-apis-app-ability-embeddableUIAbility.md)。使用Promise异步回调。 876 877**系统接口**：此接口为系统接口。 878 879**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 880 881**参数**： 882 883| 参数名 | 类型 | 必填 | 说明 | 884| ------- | -------- | -------- | -------- | 885| context | [Context](js-apis-inner-application-context.md) | 是 | 嵌入式拉起EmbeddableUIAbility的调用方Context。 | 886| appId | string | 是 | 应用的唯一标识，由云端统一分配。 | 887 888**返回值：** 889 890| 类型 | 说明 | 891| -------- | -------- | 892| Promise\<boolean> | Promise对象。返回true表示允许嵌入式启动，返回false表示不允许嵌入式启动。 | 893 894**错误码**： 895 896以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 897 898| 错误码ID | 错误信息 | 899| ------- | -------- | 900| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 901| 16000050 | Internal error. | 902 903**示例：** 904 905```ts 906import { abilityManager, UIAbility } from '@kit.AbilityKit'; 907import { BusinessError } from '@kit.BasicServicesKit'; 908 909export default class EntryAbility extends UIAbility { 910 onForeground() { 911 let appId: string = '6918661953712445909'; 912 try { 913 abilityManager.isEmbeddedOpenAllowed(this.context, appId).then((data) => { 914 console.info(`isEmbeddedOpenAllowed data: ${JSON.stringify(data)}`); 915 }).catch((err: BusinessError) => { 916 console.error(`isEmbeddedOpenAllowed failed, code is ${err.code}, message is ${err.message}`); 917 }); 918 } catch (err) { 919 // 处理入参错误异常 920 console.error(`param is invalid, code is ${err.code}, message is ${err.message}`); 921 } 922 } 923} 924``` 925 926## abilityManager.setResidentProcessEnabled<sup>12+</sup> 927 928setResidentProcessEnabled(bundleName: string, enable: boolean): Promise\<void> 929 930常驻进程支持按需启停。 931 932**系统接口**：此接口为系统接口。 933 934**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 935 936**参数**： 937 938| 参数名 | 类型 | 必填 | 说明 | 939| ------- | -------- | -------- | -------- | 940| bundleName | string | 是 | 常驻进程的包名。 | 941| enable | boolean | 是 | 常驻进程的使能状态。 true：表示该进程为常驻进程。 false：表示该进程为普通进程，不会进行保活。| 942 943**返回值：** 944 945| 类型 | 说明 | 946| -------- | -------- | 947| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 948 949**错误码**： 950 951以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 952 953| 错误码ID | 错误信息 | 954| ------- | -------- | 955| 202 | Not a system application. | 956| 401 | Parameter error. Possible cause: 1.Non empty package name needs to be provided, 2.The second parameter needs to provide a Boolean type setting value | 957| 16000050 | Internal error. | 958| 16200006 | The caller application can only set the resident status of the configured process | 959 960**示例：** 961 962```ts 963import { abilityManager } from '@kit.AbilityKit'; 964import { BusinessError } from '@kit.BasicServicesKit'; 965 966try { 967 let residentProcessBundleName: string = 'com.xxx.xxxxxx'; 968 let enable: boolean = false; 969 abilityManager.setResidentProcessEnabled(residentProcessBundleName, enable) 970 .then(() => { 971 console.log('setResidentProcessEnabled success.'); 972 }) 973 .catch((err: BusinessError) => { 974 console.error(`setResidentProcessEnabled fail, err: ${JSON.stringify(err)}`); 975 }); 976} catch (err) { 977 let code = (err as BusinessError).code; 978 let message = (err as BusinessError).message; 979 console.error(`setResidentProcessEnabled failed, code is ${code}, message is ${message}`); 980} 981``` 982