diff --git a/zh-cn/application-dev/dfx/apprecovery-guidelines.md b/zh-cn/application-dev/dfx/apprecovery-guidelines.md index 32d673bae7f18506e4062ddefe5dddac81eb8921..393083bb068e7f282675e166e24c012e2dd0e877 100644 --- a/zh-cn/application-dev/dfx/apprecovery-guidelines.md +++ b/zh-cn/application-dev/dfx/apprecovery-guidelines.md @@ -5,29 +5,48 @@ 应用在运行中不可避免会产生一些非预期的行为，如运行时抛出未处理的异常和错误，违反框架的调用/运行约束等。 系统默认对异常的处理方式为进程退出，如果应用使用过程中产生了用户数据，直接退出可能会导致用户工作中断，数据丢失。 -如果使用应用故障恢复相关接口，则可对临时数据进行保存，应用退出后会重启应用并恢复先前的状态和数据，能给用户带来更好的使用体验。 +如果应用使能了应用恢复功能，并对临时数据进行保存，应用非预期退出后的下一次启动会恢复先前的状态和数据，给用户更连贯的使用体验。这里状态包括应用的页面栈以及onSaveState接口中保存的数据。 -目前该接口仅支持单进程单Ability的Stage模型应用开发。 +API 9上的应用恢复接口支持单Ability的Stage模型应用开发。支持JsError故障时的状态保存与自动重启。 + +API 10在API 9的基础上新增支持多Ability的Stage模型应用开发。支持AppFreeze故障时的状态保存回调。支持应用被管控模式杀死后，下次启动的状态恢复。 ## 接口说明 -应用故障恢复接口由appRecovery模块提供，开发者可以通过import引入，详见[开发示例](#开发示例)。本文档描述的为API9版本的接口行为，后续接口行为变更会更新本文档。 +应用故障恢复接口由appRecovery模块提供，开发者可以通过import引入，详见[开发示例](#开发示例)。 ### 应用恢复接口功能介绍 | 接口名称 | 说明 | | ------------------------------------------------------------ | ---------------------------------------------------- | -| enableAppRecovery(restart?: RestartFlag, saveOccasion?: SaveOccasionFlag, saveMode?: SaveModeFlag) : void; | 使能应用恢复功能。| -| saveAppState(): boolean; | 主动保存当前应用中Ability的状态。 | -| restartApp(): void; | 重启当前进程，如果有已经保存的Ability状态，会在Ability的OnCreate生命周期回调的want参数中的wantParam属性传入。 | +| enableAppRecovery(restart?: RestartFlag, saveOccasion?: SaveOccasionFlag, saveMode?: SaveModeFlag) : void;9+ | 使能应用恢复功能，参数按顺序填入。该接口调用后，应用从启动器启动时第一个Ability支持恢复。| +| saveAppState(): boolean;9+ | 主动保存当前应用中支持恢复的Ability的状态。 | +| restartApp(): void;9+ | 重启当前进程，并启动由**setRestartWant**指定的Ability，如果未指定，将重新拉起处于前台且支持恢复的Ability。 | +| saveAppState(context?: UIAbilityContext): boolean;10+ | 主动保存由Context指定的Ability状态。 | +| setRestartWant(want: Want): void;10+ | 设置主动调用**restartApp**以及**RestartFlag**不为**NO_RESTART**时重启的Ability。该Ability必须在同一个包名下，且必须为**UiAbility**。 | -由于本接口为故障处理时使用，不会返回异常，需要开发者熟悉使用的场景。 +由于上述接口可能在故障处理时使用，所以不会返回异常，需要开发者熟悉使用的场景。 **enableAppRecovery:** 需要在应用初始化阶段调用，比如AbilityStage的OnCreate调用赋能。具体其各参数定义详见[参数说明](../reference/apis/js-apis-app-ability-appRecovery.md)。 -**saveAppState:** 调用后框架会回调Ability的onSaveState方法，如果在onSaveState方法中同意保存数据，则会将相关数据及Ability的页面栈持久化到应用的本地缓存。 +**saveAppState:** 调用后框架会回调**当前进程中所有支持恢复的Ability**的onSaveState方法，如果在onSaveState方法中同意保存数据，则会将相关数据及Ability的页面栈持久化到应用的本地缓存。如果需要保存指定Ability，则需要指定Ability对应的Context。 + +**setRestartWant:** 指定由appRecovery发起重启的Ability。 + +**restartApp:** 调用后框架会杀死当前应用进程，并重新拉起由**setRestartWant**指定的Ability，其中启动原因为APP_RECOVERY。API 9以及未使用**setRestartWant**指定Ability的场景，会拉起最后一个支持恢复且在前台的Ability，如果当前前台的Ability不支持恢复，则应用表现闪退。如果重启的Ability存在已经保存的状态，这些状态数据会在Ability的OnCreate生命周期回调的want参数中作为wantParam属性传入。 + +### 应用恢复状态管理示意 +从API 10起，应用恢复的场景不仅局限于异常时自动重启。所以需要理解应用何时会加载恢复的状态。 +一句话概括就是**如果应用任务的上次退出不是由用户发起的，且应用存在用于恢复的状态，应用下一次由用户拉起时的启动原因会被设为APP_RECOVERY，并清理该任务的恢复状态。** +应用恢复状态标识会在状态保存接口主动或者被动调用时设置。在该任务正常退出或者消费了该状态时清理。正常退出目前包括用户按**后退键退出**以及用户**清理最近任务**。 + +![应用恢复状态管理示意](./figures/20230315112155.png) -**restartApp:** 调用后框架会杀死当前应用进程，并重新拉起处于前台的Ability，其中启动原因为APP_RECOVERY。 +### 应用卡死的状态保存及恢复 +API 10开始支持应用卡死时的状态保存。JsError故障时，onSaveState接口在主线程进行回调。对于AppFreeze故障，主线程可能处于卡死的状态，onSaveState会在非主线程进行回调。其主要流程如下图： + +![应用卡死状态保存恢复示意](./figures/20230315112235.png) +由于卡死时的回调不在JS线程上执行，onSaveState回调中的代码建议不要使用import进来的Native动态库，禁止访问主线程创建的thread_local对象。 ### 框架故障管理流程示意 @@ -52,7 +71,7 @@ | 故障名称 | 故障监听 | 状态保存 | 自动重启 | 日志查询 | | ----------|--------- |--------- |--------- |--------- | | [JS_CRASH](../reference/apis/js-apis-faultLogger.md#faulttype) | 支持|支持|支持|支持| -| [APP_FREEZE](../reference/apis/js-apis-faultLogger.md#faulttype) | 不支持|不支持|支持|支持| +| [APP_FREEZE](../reference/apis/js-apis-faultLogger.md#faulttype) | 不支持|支持|支持|支持| | [CPP_CRASH](../reference/apis/js-apis-faultLogger.md#faulttype) | 不支持|不支持|不支持|支持| 这里状态保存指的是故障时状态保存，对于应用卡死场景，开发者可以采用定时保存状态或者在Ability切入后台后自动保存的方式最大限度的保护用户数据。 @@ -77,6 +96,18 @@ export default class MyAbilityStage extends AbilityStage { appRecovery.SaveModeFlag.SAVE_WITH_FILE); } } +``` +### 配置支持恢复的Ability +Ability的配置清单一般的名字为module.json5。 +```json +{ + "abilities": [ + { + "name": "EntryAbility", + "recoverable": true, + }] +} + ``` ### 数据保存和恢复 diff --git a/zh-cn/application-dev/dfx/figures/20230315112155.png b/zh-cn/application-dev/dfx/figures/20230315112155.png new file mode 100644 index 0000000000000000000000000000000000000000..20324a0b23f2b409c2fef8daaa74bcccd5427398 Binary files /dev/null and b/zh-cn/application-dev/dfx/figures/20230315112155.png differ diff --git a/zh-cn/application-dev/dfx/figures/20230315112235.png b/zh-cn/application-dev/dfx/figures/20230315112235.png new file mode 100644 index 0000000000000000000000000000000000000000..34cf30ce75516810536335bd9a2789517360eae3 Binary files /dev/null and b/zh-cn/application-dev/dfx/figures/20230315112235.png differ 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 a513c1d0c68d7e5386529c0ab378aee6f6cfad7f..8658417d06f5e70a9f87a3ae9555a6fa82a628fa 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 @@ -4,7 +4,7 @@ appRecovery模块提供了应用在故障状态下的恢复能力。 > **说明：** > -> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。当前版本仅支持单进程中单Ability的应用恢复。 +> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。API9仅支持单进程中单Ability的应用恢复。API10支持进程中包含多个Ability的场景。 ## 导入模块 ```ts @@ -51,7 +51,7 @@ import appRecovery from '@ohos.app.ability.appRecovery'; enableAppRecovery(restart?: [RestartFlag](#apprecoveryrestartflag), saveOccasion?: [SaveOccasionFlag](#apprecoverysaveoccasionflag), saveMode?: [SaveModeFlag](#apprecoverysavemodeflag)) : void; -使能应用恢复功能，参数按顺序填入。 +使能应用恢复功能，参数按顺序填入。该接口调用后，应用从启动器启动时第一个Ability支持恢复。 **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -84,7 +84,14 @@ export default class MyAbilityStage extends AbilityStage { restartApp(): void; -重启当前App进程，可以配合[errorManager](js-apis-app-ability-errorManager.md)相关接口使用。 +重启当前进程，并拉起应用启动时第一个Ability，如果该Ability存在已经保存的状态，这些状态数据会在Ability的OnCreate生命周期回调的want参数中作为wantParam属性传入。 + +API10时将启动由[setRestartWant](#apprecoverysetrestartwant)指定的Ability。如果没有指定则按以下规则启动：\ +如果当前应用前台的Ability支持恢复，则重新拉起该Ability。\ +如果存在多个支持恢复的Ability处于前台，则只拉起最后一个。\ +如果没有Ability处于前台，则不拉起。 + +可以配合[errorManager](js-apis-app-ability-errorManager.md)相关接口使用。 **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -142,3 +149,53 @@ try { console.error('error: ${paramError.code}, ${paramError.message}'); } ``` + +## appRecovery.saveAppState10+ + +saveAppState(context?: UIAbilityContext): boolean; + +主动保存Ability的状态，这个状态将在下次恢复启动时使用。可以配合[errorManager](js-apis-app-ability-errorManager.md)相关接口使用 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| boolean | 保存成功与否。true：保存成功，false：保存失败。 | + +**示例：** + +```ts +import appRecovery from '@ohos.app.ability.appRecovery'; +onBackground() { + hilog.info(0x0000, '[demo]', '%{public}s', 'EntryAbility onBackground'); + appRecovery.saveAppState(this.context) +} +``` + +## appRecovery.setRestartWant10+ + +setRestartWant(want: Want): void; + +设置下次恢复主动拉起场景下的Ability。该Ability必须为当前包下的UIAbility。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**示例：** + +```ts +import appRecovery from '@ohos.app.ability.appRecovery'; +Button("启动到恢复Ability") + .fontSize(40) + .fontWeight(FontWeight.Bold) + .onClick(()=> { + // set restart want + let want = { + bundleName: "ohos.samples.recovery", + abilityName: "RecoveryAbility" + }; + + appRecovery.setRestartWant(want); + }) +``` \ No newline at end of file diff --git a/zh-cn/release-notes/changelogs/OpenHarmony_4.0.5.2/changelogs-ability.md b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.5.2/changelogs-ability.md new file mode 100644 index 0000000000000000000000000000000000000000..ba5ef87f8bb33c7ffb56cba4e92e711f07248c79 --- /dev/null +++ b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.5.2/changelogs-ability.md @@ -0,0 +1,64 @@ +# 元能力子系统ChangeLog + +## cl.ability.appRecovery新增saveAppState接口 + +新增接口saveAppState(context?: UIAbilityContext): boolean; + +**变更影响** + +基于OpenHarmony4.0.5.2及之后的SDK版本开发的应用，可以使用saveAppState接口传入指定Ability Context，实现主动保存指定的Ability状态。 + +**关键接口/组件变更** + +@ohos.app.ability.appRecovery.d.ts中新增saveAppState接口。 + +| 模块名 | 类名 | 方法/属性/枚举/常量 | 变更类型 | +| -- | -- | -- | -- | +| @ohos.app.ability.appRecovery.d.ts | appRecovery | saveAppState(context?: UIAbilityContext): boolean; | 新增 | + +**适配指导** + +通过调用saveAppState传入UIAbility Context参数主动保存此指定的Ability的状态。 + +```ts +import appRecovery from '@ohos.app.ability.appRecovery'; +onBackground() { + hilog.info(0x0000, '[demo]', '%{public}s', 'EntryAbility onBackground'); + appRecovery.saveAppState(this.context) +} +``` +## cl.ability.appRecovery新增setRestartWant接口 + +新增接口setRestartWant(want: Want): void; + +**变更影响** + +基于OpenHarmony4.0.5.2及之后的SDK版本开发的应用，可以使用setRestartWant接口设置下次由恢复主动拉起场景下的Ability。 + +**关键接口/组件变更** + +@ohos.app.ability.appRecovery.d.ts中新增setRestartWant接口。 + +| 模块名 | 类名 | 方法/属性/枚举/常量 | 变更类型 | +| -- | -- | -- | -- | +| @ohos.app.ability.appRecovery.d.ts | appRecovery | setRestartWant(want: Want): void; | 新增 | + +**适配指导** + +通过调用setRestartWant设置下次恢复到的指定Ability。 + +```ts +import appRecovery from '@ohos.app.ability.appRecovery'; +Button("启动到恢复Ability") + .fontSize(40) + .fontWeight(FontWeight.Bold) + .onClick(()=> { + // set restart want + let want = { + bundleName: "ohos.samples.recovery", + abilityName: "RecoveryAbility" + }; + + appRecovery.setRestartWant(want); + }) +``` \ No newline at end of file