!16162 add AppRecovery enhance multi-mission recover function docs

Merge pull request !16162 from zhancaijin/master

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;<sup>9+</sup> | 使能应用恢复功能，参数按顺序填入。该接口调用后，应用从启动器启动时第一个Ability支持恢复。|
+| saveAppState(): boolean;<sup>9+</sup> | 主动保存当前应用中支持恢复的Ability的状态。 |
+| restartApp(): void;<sup>9+</sup> | 重启当前进程，并启动由**setRestartWant**指定的Ability，如果未指定，将重新拉起处于前台且支持恢复的Ability。 |
+| saveAppState(context?: UIAbilityContext): boolean;<sup>10+</sup> | 主动保存由Context指定的Ability状态。 |
+| setRestartWant(want: Want): void;<sup>10+</sup> | 设置主动调用**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,
+      }]
+}
+
 ```
 
 ### 数据保存和恢复

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.saveAppState<sup>10+</sup>
+
+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.setRestartWant<sup>10+</sup>
+
+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

zh-cn/release-notes/changelogs/OpenHarmony_4.0.5.2/changelogs-ability.md

+# 元能力子系统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