• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# UIAbility Backup and Restore
2
3<!--Kit: Ability Kit-->
4<!--Subsystem: Ability-->
5<!--Owner: @altay; @Luobniz21-->
6<!--Designer: @altay-->
7<!--Tester: @lixueqing513-->
8<!--Adviser: @huipeizi-->
9
10## When to Use
11
12When an application runs in the background, factors such as system resource control may cause the application to close or its process to terminate, which might result in the loss of user data. However, if the application has enabled the [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) backup and restore feature within [UIAbilityContext](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md) and saved temporary data, it can restore the previous state and data (including the page stack and the data stored in the [onSaveState](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#onsavestate) callback) when it restarts after being closed, maintaining a seamless user experience.
13
14> **NOTE**
15>
16> If the application is stopped normally, the [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) backup process is not triggered. If the application is started normally (for example, by calling the **startAbility** API or clicking the icon), the [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) restore process is not triggered.
17
18## Working Mechanism
19- [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) data backup: After an application transitions to the [onBackground](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#onbackground) lifecycle, the system automatically calls [onSaveState](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#onsavestate) to back up data.
20- [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) data restore: The restored [Want](../reference/apis-ability-kit/js-apis-app-ability-want.md) data can be obtained from the [onCreate](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#oncreate) lifecycle of the application, and the page stack data can be restored in the [onWindowStageCreate](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#onwindowstagecreate) lifecycle of the application.
21
22## Constraints
23
24- The [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) backup and restore feature supports multiple instances. Backup data is stored in the application sandbox path as files for seven days.
25
26- Backup data is stored in the **parameter** field of [Want](../reference/apis-ability-kit/js-apis-app-ability-want.md#want). Due to serialization constraints, the maximum data volume supported is 200 KB.
27
28- Data restore is unavailable after device restart.
29
30- The data backup and restore feature is unavailable for a [UIExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md).
31
32## Available APIs
33
34The [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) backup and restore API is provided by the [UIAbilityContext](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md) module. You can directly use **this.context** in the [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) to call them. For details, see [How to Develop](#how-to-develop).
35
36| API                                                      | Description                                                |
37| ------------------------------------------------------------ | ---------------------------------------------------- |
38| setRestoreEnabled(enabled: boolean): void | Sets whether to enable restore when the [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) is switched back to the foreground from the background.|
39
40[setRestoreEnabled](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#setrestoreenabled14) must be called during application initialization (before [onForeground](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#onforeground) is invoked). For example, it can be called in the [onCreate](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#oncreate) callback of the [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md).
41
42
43## How to Develop
44
45To enable [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) backup and restore during application module initialization, refer to the code snippet below.
46
47```ts
48import { UIAbility } from '@kit.AbilityKit';
49
50export default class EntryAbility extends UIAbility {
51    onCreate() {
52        console.info("[Demo] EntryAbility onCreate");
53        this.context.setRestoreEnabled(true);
54    }
55}
56```
57
58To proactively save data and restore the data when the UIAbility is started, refer to the code snippet below.
59
60```ts
61import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
62
63export default class EntryAbility extends UIAbility {
64    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
65        console.info("[Demo] EntryAbility onCreate");
66        this.context.setRestoreEnabled(true);
67        if (want && want.parameters) {
68          let recoveryMyData = want.parameters["myData"];
69        }
70    }
71
72    onSaveState(state:AbilityConstant.StateType, wantParams: Record<string, Object>) {
73        // Ability has called to save app data
74        console.log("[Demo] EntryAbility onSaveState");
75        wantParams["myData"] = "my1234567";
76        return AbilityConstant.OnSaveResult.ALL_AGREE;
77    }
78}
79```
80