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