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