1# @ohos.app.ability.appRecovery (appRecovery)
2
3appRecovery模块提供了应用在故障状态下的恢复能力。
4
5> **说明：**
6>
7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。API9仅支持单进程中单Ability的应用恢复。API10支持进程中包含多个Ability的场景。
8
9## 导入模块
10```ts
11import { appRecovery } from '@kit.AbilityKit';
12```
13
14## RestartFlag
15
16应用重启标志，[enableAppRecovery](#apprecoveryenableapprecovery)接口重启选项参数，该类型为枚举。
17
18**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。
19
20**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
21
22| 名称       | 值   | 说明       |
23| ---------- | ---- | ---------- |
24| ALWAYS_RESTART   | 0    | 总是重启应用。 |
25| RESTART_WHEN_JS_CRASH   | 0x0001    | 发生JS_CRASH时重启应用。 |
26| RESTART_WHEN_APP_FREEZE   | 0x0002    | 发生APP_FREEZE时重启应用。 |
27| NO_RESTART           | 0xFFFF    | 总是不重启应用。 |
28
29## SaveOccasionFlag
30
31保存条件标志，[enableAppRecovery](#apprecoveryenableapprecovery)接口状态保存时的选项参数，该类型为枚举。
32
33**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。
34
35**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
36
37| 名称                          | 值   | 说明                                                         |
38| ----------------------------- | ---- | ------------------------------------------------------------ |
39| SAVE_WHEN_ERROR            | 0x0001    | 当发生应用故障时保存。 |
40| SAVE_WHEN_BACKGROUND            | 0x0002    | 当应用切入后台时保存。 |
41
42## SaveModeFlag
43
44状态保存标志，[enableAppRecovery](#apprecoveryenableapprecovery)接口状态保存方式的参数，该类型为枚举。
45
46**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。
47
48**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
49
50| 名称                          | 值   | 说明                                                         |
51| ----------------------------- | ---- | ------------------------------------------------------------ |
52| SAVE_WITH_FILE             | 0x0001    | 每次状态保存都会写入到本地文件缓存。 |
53| SAVE_WITH_SHARED_MEMORY             | 0x0002    | 状态先保存在内存中，应用故障退出时写入到本地文件缓存。 |
54
55## appRecovery.enableAppRecovery
56
57enableAppRecovery(restart?: [RestartFlag](#restartflag), saveOccasion?: [SaveOccasionFlag](#saveoccasionflag), saveMode?: [SaveModeFlag](#savemodeflag)) : void
58
59使能应用恢复功能，参数按顺序填入。该接口调用后，应用从启动器启动时第一个Ability支持恢复。
60
61**模型约束**：此接口仅可在Stage模型下使用。
62
63**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。
64
65**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
66
67**参数：**
68
69| 参数名 | 类型 | 必填 | 说明 |
70| -------- | -------- | -------- | -------- |
71| restart | [RestartFlag](#restartflag) | 否 | 枚举类型，发生对应故障时是否重启，默认为重启。 |
72| saveOccasion | [SaveOccasionFlag](#saveoccasionflag) | 否 | 枚举类型，状态保存时机，默认为故障时保存。 |
73| saveMode | [SaveModeFlag](#savemodeflag) | 否 | 枚举类型，状态保存方式， 默认为文件缓存。 |
74
75**示例：**
76
77```ts
78import { appRecovery, AbilityStage } from '@kit.AbilityKit';
79
80export default class MyAbilityStage extends AbilityStage {
81  onCreate() {
82    appRecovery.enableAppRecovery(
83      appRecovery.RestartFlag.ALWAYS_RESTART,
84      appRecovery.SaveOccasionFlag.SAVE_WHEN_ERROR,
85      appRecovery.SaveModeFlag.SAVE_WITH_FILE
86    );
87  }
88}
89```
90
91## appRecovery.restartApp
92
93restartApp(): void
94
95重启当前进程，并拉起应用启动时第一个Ability，如果该Ability存在已经保存的状态，这些状态数据会在Ability的OnCreate生命周期回调的want参数中作为wantParam属性传入。
96
97API10时将启动由[setRestartWant](#apprecoverysetrestartwant10)指定的Ability。如果没有指定则按以下规则启动：\
98如果当前应用前台的Ability支持恢复，则重新拉起该Ability。\
99如果存在多个支持恢复的Ability处于前台，则只拉起最后一个。\
100如果没有Ability处于前台，则不拉起。
101
102可以配合[errorManager](js-apis-app-ability-errorManager.md)相关接口使用。两次重启的间隔应大于一分钟，一分钟之内重复调用此接口只会退出应用不会重启应用。自动重启的行为与主动重启一致。
103
104**模型约束**：此接口仅可在Stage模型下使用。
105
106**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。
107
108**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
109
110
111**示例：**
112
113```ts
114import { appRecovery, errorManager } from '@kit.AbilityKit';
115import { BusinessError } from '@kit.BasicServicesKit';
116
117let observer: errorManager.ErrorObserver = {
118  onUnhandledException(errorMsg) {
119    console.log('onUnhandledException, errorMsg: ', errorMsg);
120    appRecovery.restartApp();
121  }
122};
123
124try {
125  errorManager.on('error', observer);
126} catch (paramError) {
127  console.error(`error: ${(paramError as BusinessError).code}, ${(paramError as BusinessError).message}`);
128}
129```
130
131## appRecovery.saveAppState
132
133saveAppState(): boolean
134
135保存当前App状态，可以配合[errorManager](js-apis-app-ability-errorManager.md)相关接口使用。
136
137**模型约束**：此接口仅可在Stage模型下使用。
138
139**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。
140
141**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
142
143**返回值：**
144
145| 类型 | 说明 |
146| -------- | -------- |
147| boolean | 保存成功与否。true：保存成功，false：保存失败。 |
148
149**示例：**
150
151```ts
152import { appRecovery, errorManager } from '@kit.AbilityKit';
153import { BusinessError } from '@kit.BasicServicesKit';
154
155let observer: errorManager.ErrorObserver = {
156  onUnhandledException(errorMsg) {
157    console.log('onUnhandledException, errorMsg: ', errorMsg);
158    appRecovery.saveAppState();
159  }
160};
161
162try {
163  errorManager.on('error', observer);
164} catch (paramError) {
165  console.error(`error: ${(paramError as BusinessError).code}, ${(paramError as BusinessError).message}`);
166}
167```
168
169## appRecovery.saveAppState<sup>10+</sup>
170
171saveAppState(context?: UIAbilityContext): boolean
172
173主动保存Ability的状态，这个状态将在下次恢复启动时使用。可以配合[errorManager](js-apis-app-ability-errorManager.md)相关接口使用。
174
175**模型约束**：此接口仅可在Stage模型下使用。
176
177**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。
178
179**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
180
181**参数：**
182
183| 参数名 | 类型 | 必填 | 说明 |
184| -------- | -------- | -------- | -------- |
185| context | [UIAbilityContext](js-apis-inner-application-uiAbilityContext.md)| 否 | 需要保存状态的UIAbility所对应的context。 |
186
187**返回值：**
188
189| 类型 | 说明 |
190| -------- | -------- |
191| boolean | 保存成功与否。true：保存成功，false：保存失败。 |
192
193**示例：**
194
195```ts
196import { appRecovery, errorManager } from '@kit.AbilityKit';
197import { BusinessError } from '@kit.BasicServicesKit';
198
199let observer: errorManager.ErrorObserver = {
200  onUnhandledException(errorMsg) {
201    console.log('onUnhandledException, errorMsg: ', errorMsg);
202    appRecovery.saveAppState(this.context);
203  }
204};
205
206try {
207  errorManager.on('error', observer);
208} catch (paramError) {
209  console.error(`error: ${(paramError as BusinessError).code}, ${(paramError as BusinessError).message}`);
210}
211```
212
213## appRecovery.setRestartWant<sup>10+</sup>
214
215setRestartWant(want: Want): void
216
217设置下次恢复主动拉起场景下的Ability。该Ability必须为当前包下的UIAbility。
218
219**模型约束**：此接口仅可在Stage模型下使用。
220
221**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。
222
223**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
224
225**参数：**
226
227| 参数名 | 类型 | 必填 | 说明 |
228| -------- | -------- | -------- | -------- |
229| want | [Want](js-apis-app-ability-want.md)| 是 | 通过设置Want中"bundleName"和"abilityName"字段来指定恢复重启的Ability。 |
230
231**示例：**
232
233```ts
234import { appRecovery, Want } from '@kit.AbilityKit';
235
236@Entry
237@Component
238struct Index {
239  build() {
240    Button("启动到恢复Ability")
241      .fontSize(40)
242      .fontWeight(FontWeight.Bold)
243      .onClick(()=> {
244        // set restart want
245        let want: Want = {
246          bundleName: "ohos.samples.recovery",
247          abilityName: "RecoveryAbility"
248        };
249
250        appRecovery.setRestartWant(want);
251      })
252  }
253}
254```