1# UIAbility Lifecycle
2
3
4## Overview
5
6When a user opens or switches to and from an application, the [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) instances in the application transit in their different states. The UIAbility class provides a series of callbacks. Through these callbacks, you can know the state changes of the UIAbility instance.
7
8The lifecycle of UIAbility has four states: **Create**, **Foreground**, **Background**, and **Destroy**, as shown in the figure below.
9
10**Figure 1** UIAbility lifecycle states
11
12![Ability-Life-Cycle](figures/Ability-Life-Cycle.png)
13
14
15## Description of Lifecycle States
16
17
18### Create
19
20The **Create** state is triggered when the [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) instance is created during application loading. It corresponds to the [onCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncreate) callback. In this callback, you can perform page initialization operations, for example, defining variables or loading resources.
21
22
23```ts
24import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
25
26export default class EntryAbility extends UIAbility {
27  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
28    // Initialize the page.
29  }
30  // ...
31}
32```
33
34> **NOTE**
35>
36> [Want](../reference/apis-ability-kit/js-apis-app-ability-want.md) is used as the carrier to transfer information between application components. For details, see [Want](want-overview.md).
37
38### WindowStageCreate and WindowStageDestroy
39
40After the [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) instance is created but before it enters the Foreground state, the system creates a WindowStage instance and triggers the [onWindowStageCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate) callback. You can set UI loading and WindowStage event subscription in the callback.
41
42**Figure 2** WindowStageCreate and WindowStageDestroy
43![Ability-Life-Cycle-WindowStage](figures/Ability-Life-Cycle-WindowStage.png)
44
45In the **onWindowStageCreate()** callback, use [loadContent()](../reference/apis-arkui/js-apis-window.md#loadcontent9) to set the page to be loaded, and call [on('windowStageEvent')](../reference/apis-arkui/js-apis-window.md#onwindowstageevent9) to subscribe to [WindowStage events](../reference/apis-arkui/js-apis-window.md#windowstageeventtype9), for example, having or losing focus, switching to the foreground or background, or becoming interactive or non-interactive in the foreground.
46
47> **NOTE**
48>
49> The timing of the [WindowStage events](../reference/apis-arkui/js-apis-window.md#windowstageeventtype9) may vary according to the development scenario.
50
51```ts
52import { UIAbility } from '@kit.AbilityKit';
53import { window } from '@kit.ArkUI';
54import { hilog } from '@kit.PerformanceAnalysisKit';
55
56const TAG: string = '[EntryAbility]';
57const DOMAIN_NUMBER: number = 0xFF00;
58
59export default class EntryAbility extends UIAbility {
60  // ...
61  onWindowStageCreate(windowStage: window.WindowStage): void {
62    // Subscribe to the WindowStage events (having or losing focus, switching to the foreground or background, or becoming interactive or non-interactive in the foreground).
63    try {
64      windowStage.on('windowStageEvent', (data) => {
65        let stageEventType: window.WindowStageEventType = data;
66        switch (stageEventType) {
67          case window.WindowStageEventType.SHOWN: // Switch to the foreground.
68            hilog.info(DOMAIN_NUMBER, TAG, `windowStage foreground.`);
69            break;
70          case window.WindowStageEventType.ACTIVE: // Gain focus.
71            hilog.info(DOMAIN_NUMBER, TAG, `windowStage active.`);
72            break;
73          case window.WindowStageEventType.INACTIVE: // Lose focus.
74            hilog.info(DOMAIN_NUMBER, TAG, `windowStage inactive.`);
75            break;
76          case window.WindowStageEventType.HIDDEN: // Switch to the background.
77            hilog.info(DOMAIN_NUMBER, TAG, `windowStage background.`);
78            break;
79          case window.WindowStageEventType.RESUMED: // Interactive in the foreground.
80            hilog.info(DOMAIN_NUMBER, TAG, `windowStage resumed.`);
81            break;
82          case window.WindowStageEventType.PAUSED: // Non-interactive in the foreground.
83            hilog.info(DOMAIN_NUMBER, TAG, `windowStage paused.`);
84            break;
85          default:
86            break;
87        }
88      });
89    } catch (exception) {
90      hilog.error(DOMAIN_NUMBER, TAG,
91        `Failed to enable the listener for window stage event changes. Cause: ${JSON.stringify(exception)}`);
92    }
93    hilog.info(DOMAIN_NUMBER, TAG, `%{public}s`, `Ability onWindowStageCreate`);
94    // Set the page to be loaded.
95    windowStage.loadContent('pages/Index', (err, data) => {
96      // ...
97    });
98  }
99}
100```
101
102> **NOTE**
103>
104> For details about how to use WindowStage, see [Window Development](../windowmanager/application-window-stage.md).
105
106Before the [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) instance is destroyed, the [onWindowStageDestroy()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagedestroy) callback is invoked to release UI resources.
107
108```ts
109import { UIAbility } from '@kit.AbilityKit';
110import { window } from '@kit.ArkUI';
111
112export default class EntryAbility extends UIAbility {
113  windowStage: window.WindowStage | undefined = undefined;
114
115  // ...
116  onWindowStageCreate(windowStage: window.WindowStage): void {
117    this.windowStage = windowStage;
118    // ...
119  }
120
121  onWindowStageDestroy() {
122    // Release UI resources.
123  }
124}
125```
126
127### WindowStageWillDestroy
128The [onWindowStageWillDestroy()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagewilldestroy12) callback is invoked before the window stage is destroyed. In this case, the window stage can still be used.
129
130```ts
131import { UIAbility } from '@kit.AbilityKit';
132import { window } from '@kit.ArkUI';
133import { BusinessError } from '@kit.BasicServicesKit';
134import { hilog } from '@kit.PerformanceAnalysisKit';
135
136const TAG: string = '[EntryAbility]';
137const DOMAIN_NUMBER: number = 0xFF00;
138
139export default class EntryAbility extends UIAbility {
140  windowStage: window.WindowStage | undefined = undefined;
141  // ...
142  onWindowStageCreate(windowStage: window.WindowStage): void {
143    this.windowStage = windowStage;
144    // ...
145  }
146
147  onWindowStageWillDestroy(windowStage: window.WindowStage) {
148    // Release the resources obtained through the windowStage object.
149    // Unsubscribe from the WindowStage events (having or losing focus, switching to the foreground or background, or becoming interactive or non-interactive in the foreground) in the onWindowStageDestroy() callback.
150    try {
151      if (this.windowStage) {
152        this.windowStage.off('windowStageEvent');
153      }
154    } catch (err) {
155      let code = (err as BusinessError).code;
156      let message = (err as BusinessError).message;
157      hilog.error(DOMAIN_NUMBER, TAG, `Failed to disable the listener for windowStageEvent. Code is ${code}, message is ${message}`);
158    }
159  }
160
161  onWindowStageDestroy() {
162    // Release UI resources.
163  }
164}
165```
166
167> **NOTE**
168>
169> For details about how to use WindowStage, see [Window Development](../windowmanager/application-window-stage.md).
170
171
172### Foreground and Background
173
174The **Foreground** and **Background** states are triggered when the [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) instance is switched to the foreground and background, respectively. They correspond to the [onForeground()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonforeground) and [onBackground()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonbackground) callbacks.
175
176The **onForeground()** callback is triggered when the UI of the UIAbility instance is about to become visible, for example, when the UIAbility instance is about to enter the foreground. In this callback, you can apply for resources required by the system or re-apply for resources that have been released in the **onBackground()** callback.
177
178The **onBackground()** callback is triggered when the UI of the UIAbility instance is about to become invisible, for example, when the UIAbility instance is about to enter the background. In this callback, you can release unused resources or perform time-consuming operations such as saving the status.
179
180For example, there is an application that requires location access and has obtained the location permission from the user. Before the UI is displayed, you can enable location in the **onForeground()** callback to obtain the location information.
181
182When the application is switched to the background, you can disable location in the **onBackground()** callback to reduce system resource consumption.
183
184
185```ts
186import { UIAbility } from '@kit.AbilityKit';
187
188export default class EntryAbility extends UIAbility {
189  // ...
190
191  onForeground(): void {
192    // Apply for the resources required by the system or re-apply for the resources released in onBackground().
193  }
194
195  onBackground(): void {
196    // Release unused resources when the UI is invisible, or perform time-consuming operations in this callback,
197    // for example, saving the status.
198  }
199}
200```
201
202Assume that the application already has a UIAbility instance created, and the launch type of the UIAbility instance is set to [singleton](uiability-launch-type.md#singleton). If [startAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) is called again to start the UIAbility instance, the [onNewWant()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonnewwant) callback is invoked, but the [onCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncreate) and [onWindowStageCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate) callbacks are not. The application can update the resources and data to be loaded in the callback, which will be used for UI display.
203
204```ts
205import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
206
207export default class EntryAbility extends UIAbility {
208  // ...
209
210  onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam) {
211    // Update resources and data.
212  }
213}
214```
215
216### Destroy
217
218The Destroy state is triggered when the [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) instance is destroyed. You can perform operations such as releasing system resources and saving data in the **onDestroy()** callback.
219
220The UIAbility instance is destroyed when [terminateSelf()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateself) is called and the **onDestroy()** callback is invoked.
221<!--RP1-->The UIAbility instance is also destroyed when the user closes the instance in the system application Recents and the **onDestroy()** callback is invoked.<!--RP1End-->
222
223```ts
224import { UIAbility } from '@kit.AbilityKit';
225
226export default class EntryAbility extends UIAbility {
227  // ...
228
229  onDestroy() {
230    // Release system resources and save data.
231  }
232}
233```
234