diff --git a/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityConstant.md b/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityConstant.md index 6c4e6f0eefcbf84059e455902e9165ec330c4344..a32e9767651e5819fd88ef07e2f8da056a904a08 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityConstant.md +++ b/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityConstant.md @@ -1,8 +1,6 @@ # @ohos.app.ability.AbilityConstant (AbilityConstant) -AbilityConstant是启动参数的接口。 - -AbilityConstant提供启动参数的接口的能力，包括设置初次开始原因的类型、上次退出原因的类型、继续结果的类型。 +AbilityConstant提供Ability相关的枚举，包括设置初次启动原因、上次退出原因、迁移结果、窗口类型等。 > **说明：** > @@ -17,44 +15,74 @@ import AbilityConstant from '@ohos.app.ability.AbilityConstant'; ## 属性 +## AbilityConstant.LaunchParam + +启动参数。 + **系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core -| 名称 | 类型 | 可读 | 可写 | 说明 | +| 名称 | 类型 | 可读 | 可写 | 说明 | | -------- | -------- | -------- | -------- | -------- | -| launchReason | LaunchReason| 是 | 是 | 指示启动原因。 | -| lastExitReason | LastExitReason | 是 | 是 | 表示最后退出原因。 | +| launchReason | [LaunchReason](#abilityconstantlaunchreason)| 是 | 是 | 枚举类型，表示启动原因。 | +| lastExitReason | [LastExitReason](#abilityconstantlastexitreason) | 是 | 是 | 枚举类型，表示最后退出原因。 | ## AbilityConstant.LaunchReason -初次开始原因的类型。 +Ability初次启动原因，该类型为枚举，可配合[Ability](js-apis-app-ability-uiAbility.md)的[onCreate(want, launchParam)](js-apis-app-ability-uiAbility.md#uiabilityoncreate)方法根据launchParam.launchReason的不同类型执行相应操作。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core | 名称 | 值 | 说明 | | ----------------------------- | ---- | ------------------------------------------------------------ | -| UNKNOWN | 0 | 未知的状态。 | -| START_ABILITY | 1 | 启动能力。 | -| CALL | 2 | 呼叫。 | -| CONTINUATION | 3 | 继续。 | -| APP_RECOVERY | 4 | 状态恢复。 | +| UNKNOWN | 0 | 未知原因。 | +| START_ABILITY | 1 | 通过[startAbility](js-apis-ability-context.md#abilitycontextstartability)接口启动ability。 | +| CALL | 2 | 通过[startAbilityByCall](js-apis-ability-context.md#abilitycontextstartabilitybycall)接口启动ability。 | +| CONTINUATION | 3 | 跨端设备迁移启动ability。 | +| APP_RECOVERY | 4 | 设置应用恢复后，应用故障时自动恢复启动ability。 | + +**示例：** +```ts +import UIAbility from '@ohos.app.ability.UIAbility'; + +class MyAbility extends UIAbility { + onCreate(want, launchParam) { + if (launchParam.launchReason === AbilityConstant.LaunchReason.START_ABILITY) { + console.log("The ability has been started by the way of startAbility."); + } + } +} +``` ## AbilityConstant.LastExitReason -上次退出原因的类型。 +Ability上次退出原因，该类型为枚举，可配合[Ability](js-apis-app-ability-uiAbility.md)的[onCreate(want, launchParam)](js-apis-app-ability-uiAbility.md#uiabilityoncreate)方法根据launchParam.lastExitReason的不同类型执行相应操作。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core | 名称 | 值 | 说明 | | ----------------------------- | ---- | ------------------------------------------------------------ | -| UNKNOWN | 0 | 未知的状态。 | -| ABILITY_NOT_RESPONDING | 1 | 能力没有反应 | -| NORMAL | 2 | 正常的状态。 | +| UNKNOWN | 0 | 未知原因。 | +| ABILITY_NOT_RESPONDING | 1 | ability未响应。 | +| NORMAL | 2 | 正常退出。 | +**示例：** + +```ts +import UIAbility from '@ohos.app.ability.UIAbility'; + +class MyAbility extends UIAbility { + onCreate(want, launchParam) { + if (launchParam.lastExitReason === AbilityConstant.LastExitReason.ABILITY_NOT_RESPONDING) { + console.log("The ability has exit last because the ability was not responding."); + } + } +} +``` ## AbilityConstant.OnContinueResult -继续结果的类型。 +Ability迁移结果，该类型为枚举，可配合[Ability](js-apis-app-ability-uiAbility.md)的[onContinue(wantParam)](js-apis-app-ability-uiAbility.md#uiabilityoncontinue)方法进完成相应的返回。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core @@ -64,9 +92,21 @@ import AbilityConstant from '@ohos.app.ability.AbilityConstant'; | REJECT | 1 | 拒绝。 | | MISMATCH | 2 | 不匹配。| +**示例：** + +```ts +import UIAbility from '@ohos.app.ability.UIAbility'; + +class MyAbility extends UIAbility { + onContinue(wantParam) { + return AbilityConstant.OnConinueResult.AGREE; + } +} +``` + ## AbilityConstant.WindowMode -启动Ability时的窗口模式。 +启动Ability时的窗口模式，该类型为枚举，可配合startAbility使用指定启动Ability的窗口模式。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core @@ -78,36 +118,81 @@ import AbilityConstant from '@ohos.app.ability.AbilityConstant'; | WINDOW_MODE_SPLIT_SECONDARY | 101 | 分屏多窗口次要模式。 | | WINDOW_MODE_FLOATING | 102 | 自由悬浮形式窗口模式。 | +**示例：** + +```ts +let want = { + bundleName: "com.test.example", + abilityName: "MainAbility" +}; +let option = { + windowMode: AbilityConstant.WindowMode.WINDOW_MODE_FULLSCREEN +}; + +// 确保从上下文获取到context +this.context.startAbility(want, option).then(()={ + console.log("Succeed to start ability."); +}).catch((error)=>{ + console.log("Failed to start ability with error: " + JSON.stringify(error)); +}); +``` + ## AbilityConstant.MemoryLevel -内存级别的类型。 +内存级别，该类型为枚举，可配合[Ability](js-apis-app-ability-ability.md)的[onMemoryLevel(level)](js-apis-app-ability-ability.md#abilityonmemorylevel)方法根据level执行不同内存级别的相应操作。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core | 名称 | 值 | 说明 | -| --- | --- | --- | -| MEMORY_LEVEL_MODERATE | 0 | 内存占用适中。 | -| MEMORY_LEVEL_LOW | 1 | 内存占用低。 | +| --- | --- | --- | +| MEMORY_LEVEL_MODERATE | 0 | 内存占用适中。 | +| MEMORY_LEVEL_LOW | 1 | 内存占用低。 | | MEMORY_LEVEL_CRITICAL | 2 | 内存占用高。 | +**示例：** + +```ts +import UIAbility from '@ohos.app.ability.UIAbility'; + +class MyAbility extends UIAbility { + onMemoryLevel(level) { + if (level === AbilityConstant.MemoryLevel.MEMORY_LEVEL_CRITICAL) { + console.log("The memory of device is critical, please release some memory."); + } + } +} +``` + ## AbilityConstant.OnSaveResult -保存应用数据的结果类型。 +保存应用数据的结果，该类型为枚举，可配合[Ability](js-apis-app-ability-uiAbility.md)的[onSaveState(reason, wantParam)](js-apis-app-ability-uiAbility.md#uiabilityonsavestate)方法完成相应的返回。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core | 名称 | 值 | 说明 | | ----------------------------- | ---- | ------------------------------------------------------------ | -| ALL_AGREE | 0 | 同意保存状态。 | +| ALL_AGREE | 0 | 总是同意保存状态。 | | CONTINUATION_REJECT | 1 | 拒绝迁移保存状态。 | | CONTINUATION_MISMATCH | 2 | 迁移不匹配。| | RECOVERY_AGREE | 3 | 同意恢复保存状态。 | | RECOVERY_REJECT | 4 | 拒绝恢复保存状态。| -| ALL_REJECT | 5 | 拒绝保存状态。| +| ALL_REJECT | 5 | 总是拒绝保存状态。| + +**示例：** + +```ts +import UIAbility from '@ohos.app.ability.UIAbility'; + +class MyAbility extends UIAbility { + onSaveState(reason, wantParam) { + return AbilityConstant.OnSaveResult.ALL_AGREE; + } +} +``` ## AbilityConstant.StateType -保存应用数据场景原因类型。 +保存应用数据场景原因，该类型为枚举，可配合[Ability](js-apis-app-ability-uiAbility.md)的[onSaveState(reason, wantParam)](js-apis-app-ability-uiAbility.md#uiabilityonsavestate)方法根据reason的不同类型执行相应操作。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core @@ -115,3 +200,18 @@ import AbilityConstant from '@ohos.app.ability.AbilityConstant'; | ----------------------------- | ---- | ------------------------------------------------------------ | | CONTINUATION | 0 | 迁移保存状态。 | | APP_RECOVERY | 1 | 应用恢复保存状态。 | + +**示例：** + +```ts +import UIAbility from '@ohos.app.ability.UIAbility'; + +class MyAbility extends UIAbility { + onSaveState(reason, wantParam) { + if (reason === AbilityConstant.StateType.CONTINUATION) { + console.log("Save the ability data when the ability continuation."); + } + return AbilityConstant.OnSaveResult.ALL_AGREE; + } +} +``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityDelegatorRegistry.md b/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityDelegatorRegistry.md index f499227c419e88c2ecc3a6c484aeaa7fafcaa14f..3fb88dfc5eba562d52fa0ed6da2435ef42961d95 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityDelegatorRegistry.md +++ b/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityDelegatorRegistry.md @@ -1,26 +1,27 @@ # @ohos.app.ability.abilityDelegatorRegistry (AbilityDelegatorRegistry) -AbilityDelegatorRegistry模块提供用于存储已注册的AbilityDelegator和AbilityDelegatorArgs对象的全局寄存器的能力，包括获取应用程序的AbilityDelegator对象、获取单元测试参数AbilityDelegatorArgs对象。 +AbilityDelegatorRegistry是[测试框架](../../ability-deprecated/ability-delegator.md)模块，该模块用于获取[AbilityDelegator](js-apis-inner-application-abilityDelegator.md)和[AbilityDelegatorArgs](js-apis-inner-application-abilityDelegatorArgs.md)对象，其中[AbilityDelegator](js-apis-inner-application-abilityDelegator.md)对象提供添加用于监视指定ability的生命周期状态更改的AbilityMonitor对象的能力，[AbilityDelegatorArgs](js-apis-inner-application-abilityDelegatorArgs.md)对象提供获取当前测试参数的能力。 > **说明：** > > 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> 本模块接口仅可在测试框架中使用。 ## 导入模块 ```ts -import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry' +import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; ``` ## AbilityLifecycleState -Ability生命周期状态。 +Ability生命周期状态，该类型为枚举，可配合[AbilityDelegator](js-apis-inner-application-abilityDelegator.md)的[getAbilityState(ability)](js-apis-inner-application-abilityDelegator.md#getabilitystate9)方法返回不同ability生命周期。 **系统能力** ：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core | 名称 | 值 | 说明 | | ------------- | ---- | --------------------------- | -| UNINITIALIZED | 0 | 表示无效状态。 | +| UNINITIALIZED | 0 | 表示Ability处于无效状态。 | | CREATE | 1 | 表示Ability处于已创建状态。 | | FOREGROUND | 2 | 表示Ability处于前台状态。 | | BACKGROUND | 3 | 表示Ability处于后台状态。 | @@ -30,7 +31,7 @@ Ability生命周期状态。 getAbilityDelegator(): AbilityDelegator -获取应用程序的AbilityDelegator对象 +获取应用程序的[AbilityDelegator](js-apis-inner-application-abilityDelegator.md)对象，该对象能够使用调度测试框架的相关功能。 **系统能力：** SystemCapability.Ability.AbilityRuntime.Core @@ -43,15 +44,28 @@ getAbilityDelegator(): AbilityDelegator **示例：** ```ts -var abilityDelegator; -abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); +import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; + +let abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); + +let want = { + bundleName: "com.ohos.example", + abilityName: "MainAbility" +}; +abilityDelegator.startAbility(want, (err) => { + if (err.code !== 0) { + console.log("Success start ability."); + } else { + console.log("Failed start ability, error: " + JSON.stringify(err)); + } +}) ``` ## AbilityDelegatorRegistry.getArguments getArguments(): AbilityDelegatorArgs -获取单元测试参数AbilityDelegatorArgs对象 +获取单元测试参数[AbilityDelegatorArgs](js-apis-inner-application-abilityDelegatorArgs.md)对象。 **系统能力：** SystemCapability.Ability.AbilityRuntime.Core @@ -64,8 +78,11 @@ getArguments(): AbilityDelegatorArgs **示例：** ```ts -var args = AbilityDelegatorRegistry.getArguments(); +import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; + +let args = AbilityDelegatorRegistry.getArguments(); console.info("getArguments bundleName:" + args.bundleName); +console.info("getArguments parameters:" + JSON.stringify(args.parameters)); console.info("getArguments testCaseNames:" + args.testCaseNames); console.info("getArguments testRunnerClassName:" + args.testRunnerClassName); ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityLifecycleCallback.md b/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityLifecycleCallback.md index 16499dabc0ae7011c3f11c4e576d2754e4d5555a..919cbce9d3af5bb0991b425ea5bc1daff90b1e7d 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityLifecycleCallback.md +++ b/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityLifecycleCallback.md @@ -1,6 +1,6 @@ # @ohos.app.ability.abilityLifecycleCallback (AbilityLifecycleCallback) -AbilityLifecycleCallback模块提供应用上下文ApplicationContext的生命周期监听方法的回调类的能力，包括onAbilityCreate、onWindowStageCreate、onWindowStageDestroy等方法。 +AbilityLifecycleCallback模块提供应用上下文[ApplicationContext](js-apis-inner-application-applicationContext.md)的生命周期发生变化时触发相应回调的能力，包括[onAbilityCreate](#abilitylifecyclecallbackonabilitycreate)、[onWindowStageCreate](#abilitylifecyclecallbackonwindowstagecreate)、[onWindowStageActive](#abilitylifecyclecallbackonwindowstageactive)、[onWindowStageInactive](#abilitylifecyclecallbackonwindowstageinactive)、[onWindowStageDestroy](#abilitylifecyclecallbackonwindowstagedestroy)、[onAbilityDestroy](#abilitylifecyclecallbackonabilitydestroy)、[onAbilityForeground](#abilitylifecyclecallbackonabilityforeground)、[onAbilityBackground](#abilitylifecyclecallbackonabilitybackground)、[onAbilityContinue](#abilitylifecyclecallbackonabilitycontinue)方法。 > **说明：** > @@ -27,8 +27,16 @@ onAbilityCreate(ability: UIAbility): void; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | ability | [UIAbility](js-apis-application-ability.md#Ability) | 是 | 当前Ability对象 | + | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | 是 | 当前Ability对象 | +**示例：** +```ts +let abilityLifecycleCallback = { + onAbilityCreate(ability){ + console.log("AbilityLifecycleCallback onAbilityCreate."); + } +}; +``` ## AbilityLifecycleCallback.onWindowStageCreate @@ -42,9 +50,17 @@ onWindowStageCreate(ability: UIAbility, windowStage: window.WindowStage): void; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | ability | [UIAbility](js-apis-application-ability.md#Ability) | 是 | 当前Ability对象 | + | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | 是 | 当前Ability对象 | | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | 是 | 当前WindowStage对象 | +**示例：** +```ts +let abilityLifecycleCallback = { + onWindowStageCreate(ability, windowStage){ + console.log("AbilityLifecycleCallback onWindowStageCreate."); + } +}; +``` ## AbilityLifecycleCallback.onWindowStageActive @@ -58,9 +74,17 @@ onWindowStageActive(ability: UIAbility, windowStage: window.WindowStage): void; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | ability | [UIAbility](js-apis-application-ability.md#Ability) | 是 | 当前Ability对象 | + | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | 是 | 当前Ability对象 | | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | 是 | 当前WindowStage对象 | +**示例：** +```ts +let abilityLifecycleCallback = { + onWindowStageActive(ability, windowStage){ + console.log("AbilityLifecycleCallback onWindowStageActive."); + } +}; +``` ## AbilityLifecycleCallback.onWindowStageInactive @@ -74,9 +98,17 @@ onWindowStageInactive(ability: UIAbility, windowStage: window.WindowStage): void | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | ability | [UIAbility](js-apis-application-ability.md#Ability) | 是 | 当前Ability对象 | + | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | 是 | 当前Ability对象 | | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | 是 | 当前WindowStage对象 | +**示例：** +```ts +let abilityLifecycleCallback = { + onWindowStageInactive(ability, windowStage){ + console.log("AbilityLifecycleCallback onWindowStageInactive."); + } +}; +``` ## AbilityLifecycleCallback.onWindowStageDestroy @@ -90,9 +122,17 @@ onWindowStageDestroy(ability: UIAbility, windowStage: window.WindowStage): void; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | ability | [UIAbility](js-apis-application-ability.md#Ability) | 是 | 当前Ability对象 | + | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | 是 | 当前Ability对象 | | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | 是 | 当前WindowStage对象 | +**示例：** +```ts +let abilityLifecycleCallback = { + onWindowStageDestroy(ability, windowStage){ + console.log("AbilityLifecycleCallback onWindowStageDestroy."); + } +}; +``` ## AbilityLifecycleCallback.onAbilityDestroy @@ -106,8 +146,16 @@ onAbilityDestroy(ability: UIAbility): void; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | ability | [UIAbility](js-apis-application-ability.md#Ability) | 是 | 当前Ability对象 | + | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | 是 | 当前Ability对象 | +**示例：** +```ts +let abilityLifecycleCallback = { + onAbilityDestroy(ability){ + console.log("AbilityLifecycleCallback onAbilityDestroy."); + } +}; +``` ## AbilityLifecycleCallback.onAbilityForeground @@ -121,8 +169,16 @@ onAbilityForeground(ability: UIAbility): void; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | ability | [UIAbility](js-apis-application-ability.md#Ability) | 是 | 当前Ability对象 | + | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | 是 | 当前Ability对象 | +**示例：** +```ts +let abilityLifecycleCallback = { + onAbilityForeground(ability){ + console.log("AbilityLifecycleCallback onAbilityForeground."); + } +}; +``` ## AbilityLifecycleCallback.onAbilityBackground @@ -136,8 +192,16 @@ onAbilityBackground(ability: UIAbility): void; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | ability | [UIAbility](js-apis-application-ability.md#Ability) | 是 | 当前Ability对象 | + | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | 是 | 当前Ability对象 | +**示例：** +```ts +let abilityLifecycleCallback = { + onAbilityBackground(ability){ + console.log("AbilityLifecycleCallback onAbilityBackground."); + } +}; +``` ## AbilityLifecycleCallback.onAbilityContinue @@ -151,61 +215,89 @@ onAbilityContinue(ability: UIAbility): void; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | ability | [UIAbility](js-apis-application-ability.md#Ability) | 是 | 当前Ability对象 | + | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | 是 | 当前Ability对象 | **示例：** - - - ```ts - import UIAbility from "@ohos.app.ability.UIAbility"; - - export default class MyAbility extends UIAbility { - onCreate() { - console.log("MyAbility onCreate") - let AbilityLifecycleCallback = { - onAbilityCreate(ability){ - console.log("AbilityLifecycleCallback onAbilityCreate ability:" + JSON.stringify(ability)); - }, - onWindowStageCreate(ability, windowStage){ - console.log("AbilityLifecycleCallback onWindowStageCreate ability:" + JSON.stringify(ability)); - console.log("AbilityLifecycleCallback onWindowStageCreate windowStage:" + JSON.stringify(windowStage)); - }, - onWindowStageActive(ability, windowStage){ - console.log("AbilityLifecycleCallback onWindowStageActive ability:" + JSON.stringify(ability)); - console.log("AbilityLifecycleCallback onWindowStageActive windowStage:" + JSON.stringify(windowStage)); - }, - onWindowStageInactive(ability, windowStage){ - console.log("AbilityLifecycleCallback onWindowStageInactive ability:" + JSON.stringify(ability)); - console.log("AbilityLifecycleCallback onWindowStageInactive windowStage:" + JSON.stringify(windowStage)); - }, - onWindowStageDestroy(ability, windowStage){ - console.log("AbilityLifecycleCallback onWindowStageDestroy ability:" + JSON.stringify(ability)); - console.log("AbilityLifecycleCallback onWindowStageDestroy windowStage:" + JSON.stringify(windowStage)); - }, - onAbilityDestroy(ability){ - console.log("AbilityLifecycleCallback onAbilityDestroy ability:" + JSON.stringify(ability)); - }, - onAbilityForeground(ability){ - console.log("AbilityLifecycleCallback onAbilityForeground ability:" + JSON.stringify(ability)); - }, - onAbilityBackground(ability){ - console.log("AbilityLifecycleCallback onAbilityBackground ability:" + JSON.stringify(ability)); - }, - onAbilityContinue(ability){ - console.log("AbilityLifecycleCallback onAbilityContinue ability:" + JSON.stringify(ability)); - } - } - // 1.通过context属性获取applicationContext - let applicationContext = this.context.getApplicationContext(); - // 2.通过applicationContext注册监听应用内生命周期 - let lifecycleid = applicationContext.on("abilityLifecycle", AbilityLifecycleCallback); - console.log("registerAbilityLifecycleCallback number: " + JSON.stringify(lifecycleid)); - }, - onDestroy() { - let applicationContext = this.context.getApplicationContext(); - applicationContext.off("abilityLifecycle", lifecycleid, (error, data) => { - console.log("unregisterAbilityLifecycleCallback success, err: " + JSON.stringify(error)); - }); - } - } - ``` \ No newline at end of file +```ts +let abilityLifecycleCallback = { + onAbilityContinue(ability){ + console.log("AbilityLifecycleCallback onAbilityContinue."); + } +}; +``` + +## AbilityLifecycleCallback使用 + +**示例：** + +MyFirstAbility.ts +```ts +import AbilityLifecycleCallback from "@ohos.app.ability.AbilityLifecycleCallback"; +import AbilityStage from "@ohos.app.ability.AbilityStage"; +import UIAbility from '@ohos.app.ability.UIAbility'; + +// 声明ability生命周期回调，需配置所有回调后才可以在applicationContext注册 +let abilityLifecycleCallback = { + onAbilityCreate(ability){ + console.log("AbilityLifecycleCallback onAbilityCreate."); + }, + onWindowStageCreate(ability, windowStage){ + console.log("AbilityLifecycleCallback onWindowStageCreate."); + }, + onWindowStageActive(ability, windowStage){ + console.log("AbilityLifecycleCallback onWindowStageActive."); + }, + onWindowStageInactive(ability, windowStage){ + console.log("AbilityLifecycleCallback onWindowStageInactive."); + }, + onWindowStageDestroy(ability, windowStage){ + console.log("AbilityLifecycleCallback onWindowStageDestroy."); + }, + onAbilityDestroy(ability){ + console.log("AbilityLifecycleCallback onAbilityDestroy."); + }, + onAbilityForeground(ability){ + console.log("AbilityLifecycleCallback onAbilityForeground."); + }, + onAbilityBackground(ability){ + console.log("AbilityLifecycleCallback onAbilityBackground."); + }, + onAbilityContinue(ability){ + console.log("AbilityLifecycleCallback onAbilityContinue."); + } +}; + +export default class MyFirstAbility extends UIAbility { + onCreate() { + console.log("MyAbilityStage onCreate"); + // 1.通过context属性获取applicationContext + let applicationContext = this.context.getApplicationContext(); + // 2.通过applicationContext注册监听应用内生命周期 + try { + globalThis.lifecycleId = applicationContext.on("abilityLifecycle", abilityLifecycleCallback); + console.log("registerAbilityLifecycleCallback number: " + JSON.stringify(lifecycleId)); + } catch (paramError) { + console.log("error: " + paramError.code + " ," + paramError.message); + } + } +} +``` + +MySecondAbility.ts +```ts +import UIAbility from "ohos.app.ability.UIAbility"; + +export default class MySecondAbility extends UIAbility { + onDestroy() { + let applicationContext = this.context.getApplicationContext(); + // 3.通过applicationContext注销监听应用内生命周期 + applicationContext.off("abilityLifecycle", globalThis.lifecycleId, (error) => { + if (error.code != 0) { + console.log("unregisterAbilityLifecycleCallback failed, error: " + JSON.stringify(error)); + } else { + console.log("unregisterAbilityLifecycleCallback success."); + } + }); + } +} +``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityManager.md b/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityManager.md index c3a04a6b39291042f42fd2666ba8b175688bd0cf..2ca889c93fbe78893b5ac071bd7fbacfa836ccc7 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityManager.md +++ b/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityManager.md @@ -1,6 +1,6 @@ # @ohos.app.ability.abilityManager (AbilityManager) -AbilityManager模块提供对Ability相关信息和状态信息进行获取、新增、修改等能力。 +AbilityManager模块提供获取、新增、修改Ability相关信息和状态信息进行的能力。 > **说明：** > @@ -10,30 +10,30 @@ AbilityManager模块提供对Ability相关信息和状态信息进行获取、 ## 导入模块 ```ts -import AbilityManager from '@ohos.app.ability.abilityManager' +import abilityManager from '@ohos.app.ability.abilityManager'; ``` ## AbilityState -Ability的状态信息。 +Ability的状态，该类型为枚举，可配合[AbilityRunningInfo](js-apis-inner-application-abilityRunningInfo.md)返回Abiltiy的状态。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core -**系统API**: 此接口为系统接口，三方应用不支持调用。 +**系统API**: 此枚举类型为系统接口内部定义，三方应用不支持调用。 | 名称 | 值 | 说明 | | -------- | -------- | -------- | -| INITIAL | 0 | 表示ability为initial状态。| -| FOREGROUND | 9 | 表示ability为foreground状态。 | -| BACKGROUND | 10 | 表示ability为background状态。 | -| FOREGROUNDING | 11 | 表示ability为foregrounding状态。 | -| BACKGROUNDING | 12 | 表示ability为backgrounding状态。 | +| INITIAL | 0 | 表示ability为初始化状态。| +| FOREGROUND | 9 | 表示ability为前台状态。 | +| BACKGROUND | 10 | 表示ability为后台状态。 | +| FOREGROUNDING | 11 | 表示ability为前台调度中状态。 | +| BACKGROUNDING | 12 | 表示ability为后台调度中状态。 | ## updateConfiguration updateConfiguration(config: Configuration, callback: AsyncCallback\): void -通过修改配置来更新配置（callback形式）。 +通过传入修改的配置项来更新配置（callback形式）。 **需要权限**: ohos.permission.UPDATE_CONFIGURATION @@ -43,25 +43,42 @@ updateConfiguration(config: Configuration, callback: AsyncCallback\): void | 参数名 | 类型 | 必填 | 说明 | | --------- | ---------------------------------------- | ---- | -------------- | -| config | [Configuration](js-apis-app-ability-configuration.md) | 是 | 新的配置项。 | -| callback | AsyncCallback\ | 是 | 被指定的回调方法。 | +| config | [Configuration](js-apis-app-ability-configuration.md) | 是 | 新的配置项，仅需配置需要更新的项。 | +| callback | AsyncCallback\ | 是 | 以回调方式返回接口运行结果，可进行错误处理或其他自定义处理。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例**： ```ts -import abilitymanager from '@ohos.app.ability.abilityManager'; +import abilityManager from '@ohos.app.ability.abilityManager'; -var config = { - language: 'chinese' -} +const config = { + language: 'Zh-Hans', // 简体中文 + colorMode: COLOR_MODE_LIGHT, // 浅色模式 + direction: DIRECTION_VERTICAL, // 垂直方向 + screenDensity: SCREEN_DENSITY_SDPI, // 屏幕分辨率为"sdpi" + displayId: 1, // 应用在Id为1的物理屏上显示 + hasPointerDevice: true, // 指针类型设备已连接 +}; try { - abilitymanager.updateConfiguration(config, () => { - console.log('------------ updateConfiguration -----------'); - }) + abilityManager.updateConfiguration(config, (err) => { + if (err.code !== 0) { + console.log("updateConfiguration fail, err: " + JSON.stringify(err)); + } else { + console.log("updateConfiguration success."); + } + }) } catch (paramError) { - console.log('error.code: ' + JSON.stringify(paramError.code) + - ' error.message: ' + JSON.stringify(paramError.message)); + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); } ``` @@ -79,32 +96,45 @@ updateConfiguration(config: Configuration): Promise\ | 参数名 | 类型 | 必填 | 说明 | | --------- | ---------------------------------------- | ---- | -------------- | -| config | [Configuration](js-apis-app-ability-configuration.md) | 是 | 新的配置项。 | +| config | [Configuration](js-apis-app-ability-configuration.md) | 是 | 新的配置项，仅需配置需要更新的项。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------- | -| Promise\ | 返回执行结果。 | +| Promise\ | 以Promise方式返回接口运行结果息，可进行错误处理或其他自定义处理。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例**： ```ts -import abilitymanager from '@ohos.app.ability.abilityManager'; +import abilityManager from '@ohos.app.ability.abilityManager'; -var config = { - language: 'chinese' -} +const config = { + language: 'Zh-Hans', // 简体中文 + colorMode: COLOR_MODE_LIGHT, // 浅色模式 + direction: DIRECTION_VERTICAL, // 垂直方向 + screenDensity: SCREEN_DENSITY_SDPI, // 屏幕分辨率为"sdpi" + displayId: 1, // 应用在Id为1的物理屏上显示 + hasPointerDevice: true, // 指针类型设备已连接 +}; try { - abilitymanager.updateConfiguration(config).then(() => { - console.log('updateConfiguration success'); - }).catch((err) => { - console.log('updateConfiguration fail'); - }) + abilityManager.updateConfiguration(config).then(() => { + console.log('updateConfiguration success.'); + }).catch((err) => { + console.log('updateConfiguration fail, err: ' + JSON.stringify(err)); + }) } catch (paramError) { - console.log('error.code: ' + JSON.stringify(paramError.code) + - ' error.message: ' + JSON.stringify(paramError.message)); + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); } ``` @@ -122,20 +152,32 @@ getAbilityRunningInfos(callback: AsyncCallback\>): vo | 参数名 | 类型 | 必填 | 说明 | | --------- | ---------------------------------------- | ---- | -------------- | -| callback | AsyncCallback\> | 是 | 被指定的回调方法。 | +| callback | AsyncCallback\> | 是 | 以回调方式返回接口运行结果及运行中的ability信息，可进行错误处理或其他自定义处理。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例**： ```ts -import abilitymanager from '@ohos.app.ability.abilityManager'; +import abilityManager from '@ohos.app.ability.abilityManager'; try { - abilitymanager.getAbilityRunningInfos((err,data) => { - console.log("getAbilityRunningInfos err: " + err + " data: " + JSON.stringify(data)); - }); + abilityManager.getAbilityRunningInfos((err, data) => { + if (err.code !== 0) { + console.log("getAbilityRunningInfos fail, error: " + JSON.stringify(err)); + } else { + console.log("getAbilityRunningInfos success, data: " + JSON.stringify(data)); + } + }); } catch (paramError) { - console.log('error.code: ' + JSON.stringify(paramError.code) + - ' error.message: ' + JSON.stringify(paramError.message)); + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); } ``` @@ -153,22 +195,30 @@ getAbilityRunningInfos(): Promise\> | 类型 | 说明 | | ---------------------------------------- | ------- | -| Promise\> | 返回执行结果。 | +| Promise\> | 以Promise方式返回接口运行结果及运行中的ability信息，可进行错误处理或其他自定义处理。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例**： ```ts -import abilitymanager from '@ohos.app.ability.abilityManager'; - +import abilityManager from '@ohos.app.ability.abilityManager'; + try { - abilitymanager.getAbilityRunningInfos().then((data) => { - console.log("getAbilityRunningInfos data: " + JSON.stringify(data)) - }).catch((err) => { - console.log("getAbilityRunningInfos err: " + err) - }); + abilityManager.getAbilityRunningInfos().then((data) => { + console.log("getAbilityRunningInfos success, data: " + JSON.stringify(data)) + }).catch((err) => { + console.log("getAbilityRunningInfos fail, err: " + JSON.stringify(err)); + }); } catch (paramError) { - console.log('error.code: ' + JSON.stringify(paramError.code) + - ' error.message: ' + JSON.stringify(paramError.message)); + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); } ``` @@ -186,23 +236,35 @@ getExtensionRunningInfos(upperLimit: number, callback: AsyncCallback\> | 是 | 被指定的回调方法。 | +| upperLimit | number | 是 | 获取消息数量的最大限制，最大为231-1。 | +| callback | AsyncCallback\> | 是 | 以回调方式返回接口运行结果及运行中的extension信息，可进行错误处理或其他自定义处理。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例**： ```ts -import abilitymanager from '@ohos.app.ability.abilityManager'; +import abilityManager from '@ohos.app.ability.abilityManager'; -var upperLimit = 0; +let upperLimit = 10; try { - abilitymanager.getExtensionRunningInfos(upperLimit, (err,data) => { - console.log("getExtensionRunningInfos err: " + err + " data: " + JSON.stringify(data)); - }); + abilityManager.getExtensionRunningInfos(upperLimit, (err, data) => { + if (err.code !== 0) { + console.log("getExtensionRunningInfos fail, err: " + JSON.stringify(err)); + } else { + console.log("getExtensionRunningInfos success, data: " + JSON.stringify(data)); + } + }); } catch (paramError) { - console.log('error.code: ' + JSON.stringify(paramError.code) + - ' error.message: ' + JSON.stringify(paramError.message)); + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); } ``` @@ -220,30 +282,38 @@ getExtensionRunningInfos(upperLimit: number): Promise\31-1。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------- | -| Promise\> | 返回执行结果。 | +| Promise\> | 以Promise方式返回接口运行结果及运行中的extension信息，可进行错误处理或其他自定义处理。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例**： ```ts -import abilitymanager from '@ohos.app.ability.abilityManager'; +import abilityManager from '@ohos.app.ability.abilityManager'; -var upperLimit = 0; +let upperLimit = 10; try { - abilitymanager.getExtensionRunningInfos(upperLimit).then((data) => { - console.log("getAbilityRunningInfos data: " + JSON.stringify(data)); - }).catch((err) => { - console.log("getAbilityRunningInfos err: " + err); - }) + abilityManager.getExtensionRunningInfos(upperLimit).then((data) => { + console.log("getExtensionRunningInfos success, data: " + JSON.stringify(data)); + }).catch((err) => { + console.log("getExtensionRunningInfos fail, err: " + JSON.stringify(err)); + }) } catch (paramError) { - console.log('error.code: ' + JSON.stringify(paramError.code) + - ' error.message: ' + JSON.stringify(paramError.message)); + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); } ``` @@ -259,21 +329,28 @@ getTopAbility(callback: AsyncCallback\): void; | 参数名 | 类型 | 必填 | 说明 | | --------- | ---------------------------------------- | ---- | -------------- | -| callback | AsyncCallback\ | 是 | 被指定的回调方法。 | +| callback | AsyncCallback\<[ElementName](js-apis-bundleManager-elementName.md)> | 是 | 以回调方式返回接口运行结果及应用名，可进行错误处理或其他自定义处理。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例**： ```ts -import abilitymanager from '@ohos.app.ability.abilityManager'; - -try { - abilitymanager.getTopAbility((err,data) => { - console.log("getTopAbility err: " + err + " data: " + JSON.stringify(data)); - }); -} catch (paramError) { - console.log('error.code: ' + JSON.stringify(paramError.code) + - ' error.message: ' + JSON.stringify(paramError.message)); -} +import abilityManager from '@ohos.app.ability.abilityManager'; + +abilityManager.getTopAbility((err, data) => { + if (err.code !== 0) { + console.log("getTopAbility fail, err: " + JSON.stringify(err)); + } else { + console.log("getTopAbility success, data: " + JSON.stringify(data)); + } +}); ``` ## getTopAbility @@ -288,21 +365,24 @@ getTopAbility(): Promise\; | 类型 | 说明 | | ---------------------------------------- | ------- | -| Promise\| 返回执行结果。 | +| Promise\<[ElementName](js-apis-bundleManager-elementName.md)>| 以Promise方式返回接口运行结果及应用名，可进行错误处理或其他自定义处理。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例**： ```ts -import abilitymanager from '@ohos.app.ability.abilityManager'; +import abilityManager from '@ohos.app.ability.abilityManager'; -try { - abilitymanager.getTopAbility().then((data) => { - console.log("getTopAbility data: " + JSON.stringify(data)); - }).catch((err) => { - console.log("getTopAbility err: " + err); - }) -} catch (paramError) { - console.log('error.code: ' + JSON.stringify(paramError.code) + - ' error.message: ' + JSON.stringify(paramError.message)); -} +abilityManager.getTopAbility().then((data) => { + console.log("getTopAbility success, data: " + JSON.stringify(data)); +}).catch((err) => { + console.log("getTopAbility fail, err: " + JSON.stringify(err)); +}) ``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityStage.md b/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityStage.md index 23b02af0d62fd9283c0af456acb57a643fcb03a0..310b6df02cfdadc6ef31b9744a7cdb8937e587c8 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityStage.md +++ b/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityStage.md @@ -1,6 +1,6 @@ # @ohos.app.ability.AbilityStage (AbilityStage) -AbilityStage是HAP包的运行时类。 +AbilityStage是HAP的运行时类。 AbilityStage类提供在HAP加载的时候，通知开发者，可以在此进行该HAP的初始化（如资源预加载，线程创建等）能力。 @@ -25,13 +25,15 @@ onCreate(): void **示例：** - ```ts - class MyAbilityStage extends AbilityStage { - onCreate() { - console.log("MyAbilityStage.onCreate is called") - } - } - ``` +```ts +import AbilityStage from '@ohos.app.ability.AbilityStage'; + +class MyAbilityStage extends AbilityStage { + onCreate() { + console.log("MyAbilityStage.onCreate is called"); + } +} +``` ## AbilityStage.onAcceptWant @@ -44,9 +46,9 @@ onAcceptWant(want: Want): string; **参数：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | want | [Want](js-apis-app-ability-want.md) | 是 | Want类型参数，传入需要启动的ability的信息，如ability名称，包名等。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-app-ability-want.md) | 是 | Want类型参数，传入需要启动的ability的信息，如Ability名称，Bundle名称等。 | **返回值：** @@ -56,14 +58,16 @@ onAcceptWant(want: Want): string; **示例：** - ```ts - class MyAbilityStage extends AbilityStage { - onAcceptWant(want) { - console.log("MyAbilityStage.onAcceptWant called"); - return "com.example.test"; - } - } - ``` +```ts +import AbilityStage from '@ohos.app.ability.AbilityStage'; + +class MyAbilityStage extends AbilityStage { + onAcceptWant(want) { + console.log("MyAbilityStage.onAcceptWant called"); + return "com.example.test"; + } +} +``` ## AbilityStage.onConfigurationUpdate @@ -82,13 +86,15 @@ onConfigurationUpdate(newConfig: Configuration): void; **示例：** - ```ts - class MyAbilityStage extends AbilityStage { - onConfigurationUpdate(config) { - console.log('onConfigurationUpdate, language:' + config.language); - } - } - ``` +```ts +import AbilityStage from '@ohos.app.ability.AbilityStage'; + +class MyAbilityStage extends AbilityStage { + onConfigurationUpdate(config) { + console.log('onConfigurationUpdate, language:' + config.language); + } +} +``` ## AbilityStage.onMemoryLevel @@ -106,22 +112,24 @@ onMemoryLevel(level: AbilityConstant.MemoryLevel): void; **示例：** - ```ts - class MyAbilityStage extends AbilityStage { +```ts +import AbilityStage from '@ohos.app.ability.AbilityStage'; + +class MyAbilityStage extends AbilityStage { onMemoryLevel(level) { console.log('onMemoryLevel, level:' + JSON.stringify(level)); } - } - ``` +} +``` ## AbilityStage.context context: AbilityStageContext; -指示有关上下文的配置信息。 +指示AbilityStage的上下文。 **系统能力**：SystemCapability.Ability.AbilityRuntime.Core | 属性名 | 类型 | 说明 | | ----------- | --------------------------- | ------------------------------------------------------------ | -| context | [AbilityStageContext](js-apis-inner-application-abilityStageContext.md) | 在启动能力阶段进行初始化时回调。 | +| context | [AbilityStageContext](js-apis-inner-application-abilityStageContext.md) | 在Ability启动阶段进行初始化时回调，获取到该Ability的context值。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-app-ability-appManager.md b/zh-cn/application-dev/reference/apis/js-apis-app-ability-appManager.md index 2cc13a947bced679995fac47018c7830cd891fd0..34cec4de8bedaf1001810412b0c4430df8f065f0 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-app-ability-appManager.md +++ b/zh-cn/application-dev/reference/apis/js-apis-app-ability-appManager.md @@ -12,7 +12,7 @@ appManager模块提供App管理的能力，包括查询当前是否处于稳定 import appManager from '@ohos.app.ability.appManager'; ``` -## appManager.isRunningInStabilityTest9+ +## appManager.isRunningInStabilityTest static isRunningInStabilityTest(callback: AsyncCallback<boolean>): void @@ -20,23 +20,36 @@ static isRunningInStabilityTest(callback: AsyncCallback<boolean>): void **系统能力**：SystemCapability.Ability.AbilityRuntime.Core -**参数：** +**返回值：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<boolean> | 是 | 返回当前是否处于稳定性测试场景。 | + | 类型| 说明 | + | -------- | -------- | + |AsyncCallback<boolean> |以回调方式返回接口运行结果及当前是否处于稳定性测试场景，可进行错误处理或其他自定义处理。true: 处于稳定性测试场景，false：处于非稳定性测试场景。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例：** - - ```ts - import app from '@ohos.application.appManager'; - app.isRunningInStabilityTest((err, flag) => { - console.log('startAbility result:' + JSON.stringify(err)); - }) - ``` + +```ts +import appManager from '@ohos.app.ability.appManager'; + +appManager.isRunningInStabilityTest((err, flag) => { + if (err.code !== 0) { + console.log("isRunningInStabilityTest faile, err: " + JSON.stringify(err)); + } else { + console.log("The result of isRunningInStabilityTest is:" + JSON.stringify(flag)); + } +}) +``` -## appManager.isRunningInStabilityTest9+ +## appManager.isRunningInStabilityTest static isRunningInStabilityTest(): Promise<boolean> @@ -48,18 +61,27 @@ static isRunningInStabilityTest(): Promise<boolean> | 类型 | 说明 | | -------- | -------- | - | Promise<boolean> | 返回当前是否处于稳定性测试场景。 | + | Promise<boolean> | 以Promise方式返回接口运行结果及当前是否处于稳定性测试场景，可进行错误处理或其他自定义处理。true: 处于稳定性测试场景，false：处于非稳定性测试场景。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例：** - - ```ts - import app from '@ohos.application.appManager'; - app.isRunningInStabilityTest().then((flag) => { - console.log('success:' + JSON.stringify(flag)); - }).catch((error) => { - console.log('failed:' + JSON.stringify(error)); - }); - ``` + +```ts +import appManager from '@ohos.app.ability.appManager'; + +appManager.isRunningInStabilityTest().then((flag) => { + console.log("The result of isRunningInStabilityTest is:" + JSON.stringify(flag)); +}).catch((error) => { + console.log("error:" + JSON.stringify(error)); +}); +``` ## appManager.isRamConstrainedDevice @@ -74,17 +96,27 @@ isRamConstrainedDevice(): Promise\; | 类型 | 说明 | | -------- | -------- | - | Promise<boolean> | 是否为ram受限设备。 | + | Promise<boolean> | 以Promise方式返回接口运行结果及当前设备是否为ram受限设备，可进行错误处理或其他自定义处理。true：当前设备为ram受限设备，false：当前设备为非ram受限设备。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例：** - - ```ts - app.isRamConstrainedDevice().then((data) => { - console.log('success:' + JSON.stringify(data)); - }).catch((error) => { - console.log('failed:' + JSON.stringify(error)); - }); - ``` + +```ts +import appManager from '@ohos.app.ability.appManager'; + +appManager.isRamConstrainedDevice().then((data) => { + console.log("The result of isRamConstrainedDevice is:" + JSON.stringify(data)); +}).catch((error) => { + console.log("error:" + JSON.stringify(error)); +}); +``` ## appManager.isRamConstrainedDevice @@ -94,20 +126,33 @@ isRamConstrainedDevice(callback: AsyncCallback\): void; **系统能力**：SystemCapability.Ability.AbilityRuntime.Core -**参数：** +**返回值：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<boolean> | 是 | 返回当前是否是ram受限设备。 | + | 类型 | 说明 | + | -------- | -------- | + | AsyncCallback<boolean> |以回调方式返回接口运行结果及当前设备是否为ram受限设备，可进行错误处理或其他自定义处理。true：当前设备为ram受限设备，false：当前设备为非ram受限设备。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例：** - - ```ts - app.isRamConstrainedDevice((err, data) => { - console.log('startAbility result failed:' + JSON.stringify(err)); - console.log('startAbility result success:' + JSON.stringify(data)); - }) - ``` + +```ts +import appManager from '@ohos.app.ability.appManager'; + +appManager.isRamConstrainedDevice((err, data) => { + if (err.code !== 0) { + console.log("isRamConstrainedDevice faile, err: " + JSON.stringify(err)); + } else { + console.log("The result of isRamConstrainedDevice is:" + JSON.stringify(data)); + } +}) +``` ## appManager.getAppMemorySize @@ -121,17 +166,27 @@ getAppMemorySize(): Promise\; | 类型 | 说明 | | -------- | -------- | - | Promise<number> | 应用程序内存大小。 | + | Promise<number> | 以Promise方式返回接口运行结果及应用程序内存大小，可进行错误处理或其他自定义处理。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例：** - - ```ts - app.getAppMemorySize().then((data) => { - console.log('success:' + JSON.stringify(data)); - }).catch((error) => { - console.log('failed:' + JSON.stringify(error)); - }); - ``` + +```ts +import appManager from '@ohos.app.ability.appManager'; + +appManager.getAppMemorySize().then((data) => { + console.log("The size of app memory is:" + JSON.stringify(data)); +}).catch((error) => { + console.log("error:" + JSON.stringify(error)); +}); +``` ## appManager.getAppMemorySize @@ -141,22 +196,35 @@ getAppMemorySize(callback: AsyncCallback\): void; **系统能力**：SystemCapability.Ability.AbilityRuntime.Core -**参数：** +**返回值：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<number> | 是 | 应用程序内存大小。 | + | 类型 | 说明 | + | -------- | -------- | + |AsyncCallback<number> |以回调方式返回接口运行结果及应用程序内存大小，可进行错误处理或其他自定义处理。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例：** - - ```ts - app.getAppMemorySize((err, data) => { - console.log('startAbility result failed :' + JSON.stringify(err)); - console.log('startAbility result success:' + JSON.stringify(data)); - }) - ``` -## appManager.getProcessRunningInformation9+ +```ts +import appManager from '@ohos.app.ability.appManager'; + +appManager.getAppMemorySize((err, data) => { + if (err.code !== 0) { + console.log("getAppMemorySize faile, err: " + JSON.stringify(err)); + } else { + console.log("The size of app memory is:" + JSON.stringify(data)); + } +}) +``` + +## appManager.getProcessRunningInformation getProcessRunningInformation(): Promise\>; @@ -172,17 +240,27 @@ getProcessRunningInformation(): Promise\>; | 类型 | 说明 | | -------- | -------- | -| Promise\> | 获取有关运行进程的信息。 | +| Promise\> | 以Promise方式返回接口运行结果及有关运行进程的信息，可进行错误处理或其他自定义处理。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例：** - - ```ts - app.getProcessRunningInformation().then((data) => { - console.log('success:' + JSON.stringify(data)); - }).catch((error) => { - console.log('failed:' + JSON.stringify(error)); - }); - ``` + +```ts +import appManager from '@ohos.app.ability.appManager'; + +appManager.getProcessRunningInformation().then((data) => { + console.log("The process running information is:" + JSON.stringify(data)); +}).catch((error) => { + console.log("error:" + JSON.stringify(error)); +}); +``` ## appManager.getProcessRunningInformation9+ @@ -196,26 +274,39 @@ getProcessRunningInformation(callback: AsyncCallback\> | 是 | 获取有关运行进程的信息。 | +| 类型 | 说明 | +| -------- | -------- | +|AsyncCallback\> | 以回调方式返回接口运行结果及有关运行进程的信息，可进行错误处理或其他自定义处理。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例：** - - ```ts - app.getProcessRunningInformation((err, data) => { - console.log('startAbility result failed :' + JSON.stringify(err)); - console.log('startAbility result success:' + JSON.stringify(data)); - }) - ``` + +```ts +import appManager from '@ohos.app.ability.appManager'; + +appManager.getProcessRunningInformation((err, data) => { + if (err.code !== 0) { + console.log("getProcessRunningInformation faile, err: " + JSON.stringify(err)); + } else { + console.log("The process running information is:" + JSON.stringify(data)); + } +}) +``` ## appManager.on on(type: "applicationState", observer: ApplicationStateObserver): number; -注册全部应用程序状态观测器。 +注册全部应用程序的状态观测器。 **需要权限**：ohos.permission.RUNNING_STATE_OBSERVER @@ -227,43 +318,58 @@ on(type: "applicationState", observer: ApplicationStateObserver): number; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| type | string | 是 | 调用接口类型 | -| observer | [ApplicationStateObserver](./js-apis-inner-application-applicationStateObserver.md) | 是 | 返回观察者的数字代码。 | +| type | string | 是 | 调用接口类型，固定填"applicationState"字符串。 | +| observer | [ApplicationStateObserver](./js-apis-inner-application-applicationStateObserver.md) | 是 | 应用状态观测器，用于观测应用的生命周期变化。 | + +**返回值：** + +| 类型 | 说明 | +| --- | --- | +| number | 已注册观测器的数字代码，可用于off接口取消注册观测器。| + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例：** - - ```js - var applicationStateObserver = { + +```ts +import appManager from '@ohos.app.ability.appManager'; + +let applicationStateObserver = { onForegroundApplicationChanged(appStateData) { - console.log('------------ onForegroundApplicationChanged -----------', appStateData); + console.log(`[appManager] onForegroundApplicationChanged: ${JSON.stringify(appStateData)}`); }, onAbilityStateChanged(abilityStateData) { - console.log('------------ onAbilityStateChanged -----------', abilityStateData); + console.log(`[appManager] onAbilityStateChanged: ${JSON.stringify(abilityStateData)}`); }, onProcessCreated(processData) { - console.log('------------ onProcessCreated -----------', processData); + console.log(`[appManager] onProcessCreated: ${JSON.stringify(processData)}`); }, onProcessDied(processData) { - console.log('------------ onProcessDied -----------', processData); + console.log(`[appManager] onProcessDied: ${JSON.stringify(processData)}`); }, onProcessStateChanged(processData) { - console.log('------------ onProcessStateChanged -----------', processData); + console.log(`[appManager] onProcessStateChanged: ${JSON.stringify(processData)}`); } - } - try { - const observerCode = app.on(applicationStateObserver); - console.log('-------- observerCode: ---------', observerCode); - } catch (paramError) { - console.log('error: ' + paramError.code + ', ' + paramError.message); - } - - ``` +} +try { + const observerId = appManager.on('applicationState', applicationStateObserver); + console.log(`[appManager] observerCode: ${observerId}`); +} catch (paramError) { + console.log(`[appManager] error: ${paramError.code}, ${paramError.message} `); +} +``` ## appManager.on on(type: "applicationState", observer: ApplicationStateObserver, bundleNameList: Array\): number; -注册指定应用程序状态观测器。 +注册指定应用程序的状态观测器。 **需要权限**：ohos.permission.RUNNING_STATE_OBSERVER @@ -275,39 +381,55 @@ on(type: "applicationState", observer: ApplicationStateObserver, bundleNameList: | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| type | string | 是 | 调用接口类型 | -| observer | [ApplicationStateObserver](./js-apis-inner-application-applicationStateObserver.md) | 是 | 返回观察者的数字代码。 | -| bundleNameList | Array | 是 | 表示需要注册监听的bundleName数组。最大值128。 | +| type | string | 是 | 调用接口类型，固定填"applicationState"字符串。 | +| observer | [ApplicationStateObserver](./js-apis-inner-application-applicationStateObserver.md) | 是 | 应用状态观测器，用于观测应用的生命周期变化。 | +| bundleNameList | `Array` | 是 | 表示需要注册监听的bundleName数组。最大值128。 | + +**返回值：** + +| 类型 | 说明 | +| --- | --- | +| number | 已注册观测器的数字代码，可用于off接口注销观测器。| + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例：** - - ```js - var applicationStateObserver = { + +```ts +import appManager from '@ohos.app.ability.appManager'; + +let applicationStateObserver = { onForegroundApplicationChanged(appStateData) { - console.log('------------ onForegroundApplicationChanged -----------', appStateData); + console.log(`[appManager] onForegroundApplicationChanged: ${JSON.stringify(appStateData)}`); }, onAbilityStateChanged(abilityStateData) { - console.log('------------ onAbilityStateChanged -----------', abilityStateData); + console.log(`[appManager] onAbilityStateChanged: ${JSON.stringify(abilityStateData)}`); }, onProcessCreated(processData) { - console.log('------------ onProcessCreated -----------', processData); + console.log(`[appManager] onProcessCreated: ${JSON.stringify(processData)}`); }, onProcessDied(processData) { - console.log('------------ onProcessDied -----------', processData); + console.log(`[appManager] onProcessDied: ${JSON.stringify(processData)}`); }, onProcessStateChanged(processData) { - console.log('------------ onProcessStateChanged -----------', processData); + console.log(`[appManager] onProcessStateChanged: ${JSON.stringify(processData)}`); } - } - var bundleNameList = ['bundleName1', 'bundleName2']; - try { - const observerCode = app.on("applicationState", applicationStateObserver, bundleNameList); - console.log('-------- observerCode: ---------', observerCode); - } catch (paramError) { - console.log('error: ' + paramError.code + ', ' + paramError.message); - } +} +let bundleNameList = ['bundleName1', 'bundleName2']; +try { + const observerId = appManager.on("applicationState", applicationStateObserver, bundleNameList); + console.log(`[appManager] observerCode: ${observerId}`); +} catch (paramError) { + console.log(`[appManager] error: ${paramError.code}, ${paramError.message} `); +} +``` - ``` ## appManager.off off(type: "applicationState", observerId: number, callback: AsyncCallback\): void; @@ -321,29 +443,68 @@ off(type: "applicationState", observerId: number, callback: AsyncCallback\ | 是 | 表示指定的回调方法。 | +| type | string | 是 | 调用接口类型，固定填"applicationState"字符串。 | +| observerId | number | 是 | 表示观测器的编号代码。 | +| callback | AsyncCallback\ | 是 | 以回调方式返回接口运行结果，可进行错误处理或其他自定义处理。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例：** - - ```js - var observerId = 100; - function unregisterApplicationStateObserverCallback(err) { - if (err) { - console.log('------------ unregisterApplicationStateObserverCallback ------------', err); - } +```ts +import appManager from '@ohos.app.ability.appManager'; + +let observeId = 0; + +// 1.注册应用状态监听器 +let applicationStateObserver = { + onForegroundApplicationChanged(appStateData) { + console.log(`[appManager] onForegroundApplicationChanged: ${JSON.stringify(appStateData)}`); + }, + onAbilityStateChanged(abilityStateData) { + console.log(`[appManager] onAbilityStateChanged: ${JSON.stringify(abilityStateData)}`); + }, + onProcessCreated(processData) { + console.log(`[appManager] onProcessCreated: ${JSON.stringify(processData)}`); + }, + onProcessDied(processData) { + console.log(`[appManager] onProcessDied: ${JSON.stringify(processData)}`); + }, + onProcessStateChanged(processData) { + console.log(`[appManager] onProcessStateChanged: ${JSON.stringify(processData)}`); } - try { - app.off(observerId, unregisterApplicationStateObserverCallback); - } catch (paramError) { - console.log('error: ' + paramError.code + ', ' + paramError.message); +} +let bundleNameList = ['bundleName1', 'bundleName2']; +try { + observerId = appManager.on("applicationState", applicationStateObserver, bundleNameList); + console.log(`[appManager] observerCode: ${observerId}`); +} catch (paramError) { + console.log(`[appManager] error: ${paramError.code}, ${paramError.message} `); +} + +// 2.注销应用状态监听器 +function unregisterApplicationStateObserverCallback(err) { + if (err.code !== 0) { + console.log("unregisterApplicationStateObserverCallback faile, err: " + JSON.stringify(err)); + } else { + console.log("unregisterApplicationStateObserverCallback success."); } - ``` +} +try { + appManager.off("applicationState", observerId, unregisterApplicationStateObserverCallback); +} catch (paramError) { + console.log('error: ' + paramError.code + ', ' + paramError.message); +} +``` ## appManager.off @@ -361,38 +522,73 @@ off(type: "applicationState", observerId: number): Promise\; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| type | string | 是 | 调用接口类型 | -| observerId | number | 是 | 表示观察者的编号代码。 | +| type | string | 是 | 调用接口类型，固定填"applicationState"字符串。 | +| observerId | number | 是 | 表示观测器的编号代码。 | **返回值：** | 类型 | 说明 | | -------- | -------- | -| Promise\ | 返回执行结果。 | +| Promise\ | 以Promise方式返回接口运行结果，可进行错误处理或其他自定义处理。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例：** - - ```js - var observerId = 100; - - try { - app.off(observerId) - .then((data) => { - console.log('----------- unregisterApplicationStateObserver success ----------', data); - }) - .catch((err) => { - console.log('----------- unregisterApplicationStateObserver fail ----------', err); - }) - } catch (paramError) { - console.log('error: ' + paramError.code + ', ' + paramError.message); + +```ts +import appManager from '@ohos.app.ability.appManager'; + +let observeId = 0; + +// 1.注册应用状态监听器 +let applicationStateObserver = { + onForegroundApplicationChanged(appStateData) { + console.log(`[appManager] onForegroundApplicationChanged: ${JSON.stringify(appStateData)}`); + }, + onAbilityStateChanged(abilityStateData) { + console.log(`[appManager] onAbilityStateChanged: ${JSON.stringify(abilityStateData)}`); + }, + onProcessCreated(processData) { + console.log(`[appManager] onProcessCreated: ${JSON.stringify(processData)}`); + }, + onProcessDied(processData) { + console.log(`[appManager] onProcessDied: ${JSON.stringify(processData)}`); + }, + onProcessStateChanged(processData) { + console.log(`[appManager] onProcessStateChanged: ${JSON.stringify(processData)}`); } - ``` +} +let bundleNameList = ['bundleName1', 'bundleName2']; +try { + observerId = appManager.on("applicationState", applicationStateObserver, bundleNameList); + console.log(`[appManager] observerCode: ${observerId}`); +} catch (paramError) { + console.log(`[appManager] error: ${paramError.code}, ${paramError.message} `); +} + +// 2.注销应用状态监听器 +try { + appManager.off("applicationState", observerId).then((data) => { + console.log("unregisterApplicationStateObserver success, data: " + JSON.stringify(data)); + }).catch((err) => { + console.log("unregisterApplicationStateObserver faile, err: " + JSON.stringify(err)); + }) +} catch (paramError) { + console.log('error: ' + paramError.code + ', ' + paramError.message); +} +``` ## appManager.getForegroundApplications getForegroundApplications(callback: AsyncCallback\>): void; -获取前台进程的应用程序。 +获取当前所有前台应用的信息。该应用信息由[AppStateData](js-apis-inner-application-appStateData.md)定义。 **需要权限**：ohos.permission.GET_RUNNING_INFO @@ -400,96 +596,44 @@ getForegroundApplications(callback: AsyncCallback\>): void; **系统API**：该接口为系统接口，三方应用不支持调用。 -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback\> | 是 | 表示应用的状态数据。 | - -**示例：** - - ```js - function getForegroundApplicationsCallback(err, data) { - if (err) { - console.log('--------- getForegroundApplicationsCallback fail ---------', err.code + ': ' + err.message); - } else { - console.log('--------- getForegroundApplicationsCallback success ---------', data) - } - } - app.getForegroundApplications(getForegroundApplicationsCallback); - ``` - -unregisterApplicationStateObserver(observerId: number): Promise\; - -取消注册应用程序状态观测器。 +**错误码**： -**需要权限**：ohos.permission.RUNNING_STATE_OBSERVER +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | -**系统能力**：SystemCapability.Ability.AbilityRuntime.Core - -**系统API**：该接口为系统接口，三方应用不支持调用。 +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| observerId | number | 是 | 表示观察者的编号代码。 | - -**返回值：** - -| 类型 | 说明 | -| -------- | -------- | -| Promise\ | 返回执行结果。 | +| callback | AsyncCallback\> | 是 | 以Promise方式返回接口运行结果及应用状态数据数组，可进行错误处理或其他自定义处理。 | **示例：** - - ```ts - var observerId = 100; - app.unregisterApplicationStateObserver(observerId) - .then((data) => { - console.log('----------- unregisterApplicationStateObserver success ----------', data); - }) - .catch((err) => { - console.log('----------- unregisterApplicationStateObserver fail ----------', err); - }) - ``` - -## appManager.getForegroundApplications9+ - -getForegroundApplications(callback: AsyncCallback\>): void; - -获取前台进程的应用程序。 -**需要权限**：ohos.permission.GET_RUNNING_INFO - -**系统能力**：SystemCapability.Ability.AbilityRuntime.Core - -**系统API**：该接口为系统接口，三方应用不支持调用。 - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback\> | 是 | 表示应用的状态数据。 | +```ts +import appManager from '@ohos.app.ability.appManager'; -**示例：** - - ```ts - function getForegroundApplicationsCallback(err, data) { - if (err) { - console.log('--------- getForegroundApplicationsCallback fail ---------', err); +function getForegroundApplicationsCallback(err, data) { + if (err.code !== 0) { + console.log("getForegroundApplicationsCallback fail, err: " + JSON.stringify(err)); } else { - console.log('--------- getForegroundApplicationsCallback success ---------', data) + console.log("getForegroundApplicationsCallback success, data: " + JSON.stringify(data)); } - } - app.getForegroundApplications(getForegroundApplicationsCallback); - ``` +} +try { + appManager.getForegroundApplications(getForegroundApplicationsCallback); +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` -## appManager.getForegroundApplications9+ +## appManager.getForegroundApplications getForegroundApplications(): Promise\>; -获取前台进程的应用程序。 +获取当前所有前台应用的信息。该应用信息由[AppStateData](js-apis-inner-application-appStateData.md)定义。 **需要权限**：ohos.permission.GET_RUNNING_INFO @@ -501,27 +645,35 @@ getForegroundApplications(): Promise\>; | 类型 | 说明 | | -------- | -------- | -| Promise\> | 返回进程运行信息的数组。 | +| Promise\> | 返回前台进程应用程序的数组。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例：** - - ```ts - app.getForegroundApplications() - .then((data) => { - console.log('--------- getForegroundApplications success -------', data); - }) - .catch((err) => { - console.log('--------- getForegroundApplications fail -------', err); - }) - ``` - -## appManager.killProcessWithAccount9+ + +```ts +import appManager from '@ohos.app.ability.appManager'; + +appManager.getForegroundApplications().then((data) => { + console.log("getForegroundApplications success, data: " + JSON.stringify(data)); +}).catch((err) => { + console.log("getForegroundApplications fail, err: " + JSON.stringify(err)); +}) +``` + +## appManager.killProcessWithAccount killProcessWithAccount(bundleName: string, accountId: number): Promise\ 切断account进程（Promise形式）。 -**需要权限**：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS, ohos.permission.CLEAN_BACKGROUND_PROCESSES +**需要权限**：ohos.permission.CLEAN_BACKGROUND_PROCESSES，ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS，当accountId为当前用户时，不需要校验ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS权限。 **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -529,27 +681,39 @@ killProcessWithAccount(bundleName: string, accountId: number): Promise\ **参数：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | bundleName | string | 是 | 应用包名。 | - | accountId | number | 是 | 系统帐号的帐号ID，详情参考[getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess)。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| bundleName | string | 是 | 应用Bundle名称。 | +| accountId | number | 是 | 系统帐号的帐号ID，详情参考[getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess)。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例：** ```ts -var bundleName = 'bundleName'; -var accountId = 0; -app.killProcessWithAccount(bundleName, accountId) - .then((data) => { - console.log('------------ killProcessWithAccount success ------------', data); - }) - .catch((err) => { - console.log('------------ killProcessWithAccount fail ------------', err); - }) +import appManager from '@ohos.app.ability.appManager'; + +let bundleName = 'bundleName'; +let accountId = 0; +try { + appManager.killProcessWithAccount(bundleName, accountId).then(() => { + console.log("killProcessWithAccount success"); + }).catch((err) => { + console.log("killProcessWithAccount fail, err: " + JSON.stringify(err)); + }) +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} ``` -## appManager.killProcessWithAccount9+ +## appManager.killProcessWithAccount killProcessWithAccount(bundleName: string, accountId: number, callback: AsyncCallback\): void @@ -559,36 +723,46 @@ killProcessWithAccount(bundleName: string, accountId: number, callback: AsyncCal **系统API**: 此接口为系统接口，三方应用不支持调用。 -**需要权限**：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS, ohos.permission.CLEAN_BACKGROUND_PROCESSES +**需要权限**：ohos.permission.CLEAN_BACKGROUND_PROCESSES，ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS，当accountId为当前用户时，不需要校验ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS权限。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | bundleName | string | 是 | 应用包名。 | + | bundleName | string | 是 | 应用Bundle名称。 | | accountId | number | 是 | 系统帐号的帐号ID，详情参考[getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess)。 | - | callback | AsyncCallback\ | 是 | 切断account进程的回调函数。 | + | callback | AsyncCallback\ | 是 | 以回调方式返回接口运行结果，可进行错误处理或其他自定义处理。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例：** ```ts -var bundleName = 'bundleName'; -var accountId = 0; +import appManager from '@ohos.app.ability.appManager'; + +let bundleName = 'bundleName'; +let accountId = 0; function killProcessWithAccountCallback(err, data) { - if (err) { - console.log('------------- killProcessWithAccountCallback fail, err: --------------', err); - } else { - console.log('------------- killProcessWithAccountCallback success, data: --------------', data); - } + if (err.code !== 0) { + console.log("killProcessWithAccountCallback fail, err: " + JSON.stringify(err)); + } else { + console.log("killProcessWithAccountCallback success."); + } } -app.killProcessWithAccount(bundleName, accountId, killProcessWithAccountCallback); +appManager.killProcessWithAccount(bundleName, accountId, killProcessWithAccountCallback); ``` -## appManager.killProcessesByBundleName9+ +## appManager.killProcessesByBundleName killProcessesByBundleName(bundleName: string, callback: AsyncCallback\); -通过包名终止进程。 +通过Bundle名称终止进程。 **需要权限**：ohos.permission.CLEAN_BACKGROUND_PROCESSES @@ -600,28 +774,42 @@ killProcessesByBundleName(bundleName: string, callback: AsyncCallback\); | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| bundleName | string | 是 | 表示包名。 | -| callback | AsyncCallback\ | 是 | 表示指定的回调方法。 | +| bundleName | string | 是 | 表示Bundle名称。 | +| callback | AsyncCallback\ | 是 | 以回调方式返回接口运行结果，可进行错误处理或其他自定义处理。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例：** - - ```ts - var bundleName = 'bundleName'; - function killProcessesByBundleNameCallback(err, data) { - if (err) { - console.log('------------- killProcessesByBundleNameCallback fail, err: --------------', err); + +```ts +import appManager from '@ohos.app.ability.appManager'; + +let bundleName = 'bundleName'; +function killProcessesByBundleNameCallback(err, data) { + if (err.code !== 0) { + console.log("killProcessesByBundleNameCallback fail, err: " + JSON.stringify(err)); } else { - console.log('------------- killProcessesByBundleNameCallback success, data: --------------', data); + console.log("killProcessesByBundleNameCallback success."); } - } - app.killProcessesByBundleName(bundleName, killProcessesByBundleNameCallback); - ``` +} +try { + appManager.killProcessesByBundleName(bundleName, killProcessesByBundleNameCallback); +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` -## appManager.killProcessesByBundleName9+ +## appManager.killProcessesByBundleName killProcessesByBundleName(bundleName: string): Promise\; -通过包名终止进程。 +通过Bundle名称终止进程。 **需要权限**：ohos.permission.CLEAN_BACKGROUND_PROCESSES @@ -633,7 +821,7 @@ killProcessesByBundleName(bundleName: string): Promise\; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| bundleName | string | 是 | 表示包名。 | +| bundleName | string | 是 | 表示Bundle名称。 | **返回值：** @@ -641,24 +829,36 @@ killProcessesByBundleName(bundleName: string): Promise\; | -------- | -------- | | Promise\ | 返回执行结果。 | +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 + **示例：** - - ```ts -var bundleName = 'bundleName'; -app.killProcessesByBundleName(bundleName) - .then((data) => { - console.log('------------ killProcessesByBundleName success ------------', data); - }) - .catch((err) => { - console.log('------------ killProcessesByBundleName fail ------------', err); - }) - ``` - -## appManager.clearUpApplicationData9+ + +```ts +import appManager from '@ohos.app.ability.appManager'; + +let bundleName = 'bundleName'; +try { + appManager.killProcessesByBundleName(bundleName).then((data) => { + console.log("killProcessesByBundleName success."); + }).catch((err) => { + console.log("killProcessesByBundleName fail, err: " + JSON.stringify(err)); + }) +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` + +## appManager.clearUpApplicationData clearUpApplicationData(bundleName: string, callback: AsyncCallback\); -通过包名清除应用数据。 +通过Bundle名称清除应用数据。 **需要权限**：ohos.permission.CLEAN_APPLICATION_DATA @@ -670,28 +870,42 @@ clearUpApplicationData(bundleName: string, callback: AsyncCallback\); | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| bundleName | string | 是 | 表示包名。 | -| callback | AsyncCallback\ | 是 | 表示指定的回调方法。 | +| bundleName | string | 是 | 表示Bundle名称。 | +| callback | AsyncCallback\ | 是 | 以回调方式返回接口运行结果，可进行错误处理或其他自定义处理。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例：** - - ```ts - var bundleName = 'bundleName'; - function clearUpApplicationDataCallback(err, data) { + +```ts +import appManager from '@ohos.app.ability.appManager'; + +let bundleName = 'bundleName'; +function clearUpApplicationDataCallback(err, data) { if (err) { - console.log('------------- clearUpApplicationDataCallback fail, err: --------------', err); + console.log("clearUpApplicationDataCallback fail, err: " + JSON.stringify(err)); } else { - console.log('------------- clearUpApplicationDataCallback success, data: --------------', data); + console.log("clearUpApplicationDataCallback success."); } - } - app.clearUpApplicationData(bundleName, clearUpApplicationDataCallback); - ``` +} +try { + appManager.clearUpApplicationData(bundleName, clearUpApplicationDataCallback); +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` -## appManager.clearUpApplicationData9+ +## appManager.clearUpApplicationData clearUpApplicationData(bundleName: string): Promise\; -通过包名清除应用数据。 +通过Bundle名称清除应用数据。 **需要权限**：ohos.permission.CLEAN_APPLICATION_DATA @@ -703,28 +917,42 @@ clearUpApplicationData(bundleName: string): Promise\; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| bundleName | string | 是 | 表示包名。 | +| bundleName | string | 是 | 表示Bundle名称。 | **返回值：** | 类型 | 说明 | | -------- | -------- | -| Promise\ | 返回执行结果。 | +| Promise\ | 以Promise方式返回接口运行结果，可进行错误处理或其他自定义处理。 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 **示例：** - - ```ts - var bundleName = 'bundleName'; - app.clearUpApplicationData(bundleName) - .then((data) => { - console.log('------------ clearUpApplicationData success ------------', data); - }) - .catch((err) => { - console.log('------------ clearUpApplicationData fail ------------', err); + +```ts +import appManager from '@ohos.app.ability.appManager'; + +let bundleName = 'bundleName'; +try { + appManager.clearUpApplicationData(bundleName).then((data) => { + console.log("clearUpApplicationData success."); + }).catch((err) => { + console.log("clearUpApplicationData fail, err: " + JSON.stringify(err)); }) - ``` +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` -## ApplicationState9+ +## ApplicationState + +应用状态，该类型为枚举，可配合[AbilityStateData](js-apis-inner-application-appStateData.md)返回相应的应用状态。 **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -738,7 +966,9 @@ clearUpApplicationData(bundleName: string): Promise\; | STATE_BACKGROUND | 4 | 当应用处于后台不可见时处于的状态。 | | STATE_DESTROY | 5 | 当应用在销毁的时候处于的状态。 | -## ProcessState9+ +## ProcessState + +进程状态，该类型为枚举，可配合[ProcessData](js-apis-inner-application-processData.md)返回相应的进程状态。 **系统能力**：SystemCapability.Ability.AbilityRuntime.Core diff --git a/zh-cn/application-dev/reference/apis/js-apis-app-ability-appRecovery.md b/zh-cn/application-dev/reference/apis/js-apis-app-ability-appRecovery.md index dea9c02adaff656f336a7a9b53299c02f26a16af..72c8116699a3130bdb0fe7bd1045e2f14ef50955 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-app-ability-appRecovery.md +++ b/zh-cn/application-dev/reference/apis/js-apis-app-ability-appRecovery.md @@ -8,13 +8,13 @@ appRecovery模块提供了应用在故障状态下的恢复能力。 ## 导入模块 ```ts -import appRecovery from '@ohos.app.ability.appRecovery' +import appRecovery from '@ohos.app.ability.appRecovery'; ``` ## appRecovery.RestartFlag -[enableAppRecovery](#apprecoveryenableapprecovery)接口重启选项参数。 +应用重启标志，[enableAppRecovery](#apprecoveryenableapprecovery)接口重启选项参数，该类型为枚举。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core @@ -28,7 +28,7 @@ import appRecovery from '@ohos.app.ability.appRecovery' ## appRecovery.SaveOccasionFlag -[enableAppRecovery](#apprecoveryenableapprecovery)接口状态保存时机选项参数。 +保存条件标志，[enableAppRecovery](#apprecoveryenableapprecovery)接口状态保存时的选项参数，该类型为枚举。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core @@ -39,7 +39,7 @@ import appRecovery from '@ohos.app.ability.appRecovery' ## appRecovery.SaveModeFlag -[enableAppRecovery](#apprecoveryenableapprecovery)接口状态保存方式的参数。 +状态保存标志，[enableAppRecovery](#apprecoveryenableapprecovery)接口状态保存方式的参数，该类型为枚举。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core @@ -50,7 +50,7 @@ import appRecovery from '@ohos.app.ability.appRecovery' ## appRecovery.enableAppRecovery -enableAppRecovery(restart?: RestartFlag, saveOccasion?: SaveOccasionFlag, saveMode?: SaveModeFlag) : void; +enableAppRecovery(restart?: [RestartFlag](#apprecoveryrestartflag), saveOccasion?: [SaveOccasionFlag](#apprecoverysaveoccasionflag), saveMode?: [SaveModeFlag](#apprecoverysavemodeflag)) : void; 使能应用恢复功能，参数按顺序填入。 @@ -60,16 +60,24 @@ enableAppRecovery(restart?: RestartFlag, saveOccasion?: SaveOccasionFlag, saveMo | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| restart | [RestartFlag](#apprecoveryrestartflag) | 否 | 发生对应故障时是否重启，默认为不重启。 | -| saveOccasion | [SaveOccasionFlag](#apprecoverysaveoccasionflag) | 否 | 状态保存时机，默认为故障时保存。 | -| saveMode | [SaveModeFlag](#apprecoverysavemodeflag) | 否 | 状态保存方式， 默认为文件缓存。 | +| restart | [RestartFlag](#apprecoveryrestartflag) | 否 | 枚举类型，发生对应故障时是否重启，默认为不重启。 | +| saveOccasion | [SaveOccasionFlag](#apprecoverysaveoccasionflag) | 否 | 枚举类型，状态保存时机，默认为故障时保存。 | +| saveMode | [SaveModeFlag](#apprecoverysavemodeflag) | 否 | 枚举类型，状态保存方式， 默认为文件缓存。 | **示例：** ```ts -export default class MyAbilityStage extends AbilityStage { +import appRecovery from '@ohos.app.ability.appRecovery'; +import AbilityStage from '@ohos.app.ability.AbilityStage'; +import UIAbility from '@ohos.app.ability.UIAbility'; + +export default class MyAbility extends UIAbility { onCreate() { - appRecovery.enableAppRecovery(RestartFlag::ALWAYS_RESTART, SaveOccasionFlag::SAVE_WHEN_ERROR, SaveModeFlag::SAVE_WITH_FILE); + appRecovery.enableAppRecovery( + appRecovery.RestartFlag::ALWAYS_RESTART, + appRecovery.SaveOccasionFlag::SAVE_WHEN_ERROR, + appRecovery.SaveModeFlag::SAVE_WITH_FILE + ); } } ``` @@ -86,13 +94,21 @@ restartApp(): void; **示例：** ```ts -var observer = { +import appRecovery from '@ohos.app.ability.appRecovery'; +import errorManager from '@ohos.app.ability.errorManager'; + +let observer = { onUnhandledException(errorMsg) { console.log('onUnhandledException, errorMsg: ', errorMsg) appRecovery.restartApp(); } -} +}; +try { + errorManager.on("error", observer); +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} ``` ## appRecovery.saveAppState @@ -107,15 +123,24 @@ saveAppState(): boolean; | 类型 | 说明 | | -------- | -------- | -| boolean | 保存成功与否。 | +| boolean | 保存成功与否。true：保存成功，false：保存失败。 | **示例：** ```ts -var observer = { +import appRecovery from '@ohos.app.ability.appRecovery'; +import errorManager from '@ohos.app.ability.errorManager'; + +let observer = { onUnhandledException(errorMsg) { console.log('onUnhandledException, errorMsg: ', errorMsg) appRecovery.saveAppState(); } +}; + +try { + errorManager.on("error", observer); +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); } ```