js-apis-app-ability-abilityLifecycleCallback.md 10.0 KB
Newer Older
Z
zengyawen 已提交
1
# @ohos.app.ability.abilityLifecycleCallback (AbilityLifecycleCallback)
D
donglin 已提交
2

D
donglin 已提交
3
AbilityLifecycleCallback模块提供应用上下文[ApplicationContext](js-apis-inner-application-applicationContext.md)的生命周期发生变化时触发相应回调的能力,包括[onAbilityCreate](#abilitylifecyclecallbackonabilitycreate)[onWindowStageCreate](#abilitylifecyclecallbackonwindowstagecreate)[onWindowStageActive](#abilitylifecyclecallbackonwindowstageactive)[onWindowStageInactive](#abilitylifecyclecallbackonwindowstageinactive)[onWindowStageDestroy](#abilitylifecyclecallbackonwindowstagedestroy)[onAbilityDestroy](#abilitylifecyclecallbackonabilitydestroy)[onAbilityForeground](#abilitylifecyclecallbackonabilityforeground)[onAbilityBackground](#abilitylifecyclecallbackonabilitybackground)[onAbilityContinue](#abilitylifecyclecallbackonabilitycontinue)方法。
D
donglin 已提交
4 5 6 7 8 9 10 11 12

> **说明:**
> 
> 本模块首批接口从API version 9 开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。  
> 本模块接口仅可在Stage模型下使用。


## 导入模块

M
m00512953 已提交
13
```ts
D
donglin 已提交
14 15 16 17 18 19
import AbilityLifecycleCallback from "@ohos.app.ability.AbilityLifecycleCallback";
```


## AbilityLifecycleCallback.onAbilityCreate

D
fix  
donglin 已提交
20
onAbilityCreate(ability: UIAbility): void;
D
donglin 已提交
21 22 23 24 25 26 27 28 29

注册监听应用上下文的生命周期后,在ability创建时触发回调。

**系统能力**:SystemCapability.Ability.AbilityRuntime.AbilityCore

**参数:**

  | 参数名 | 类型 | 必填 | 说明 | 
  | -------- | -------- | -------- | -------- |
D
donglin 已提交
30
  | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | 是 | 当前Ability对象 | 
D
donglin 已提交
31

D
donglin 已提交
32 33 34 35 36 37
**示例:**
```ts
let abilityLifecycleCallback =  {
    onAbilityCreate(ability){
        console.log("AbilityLifecycleCallback onAbilityCreate.");  
    }
38
};
D
donglin 已提交
39
```
D
donglin 已提交
40 41 42

## AbilityLifecycleCallback.onWindowStageCreate

D
fix  
donglin 已提交
43
onWindowStageCreate(ability: UIAbility, windowStage: window.WindowStage): void;
D
donglin 已提交
44 45 46 47 48 49 50 51 52

注册监听应用上下文的生命周期后,在windowStage创建时触发回调。

**系统能力**:SystemCapability.Ability.AbilityRuntime.AbilityCore

**参数:**

  | 参数名 | 类型 | 必填 | 说明 | 
  | -------- | -------- | -------- | -------- |
D
donglin 已提交
53
  | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | 是 | 当前Ability对象 |  
D
donglin 已提交
54
  | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | 是 | 当前WindowStage对象 |    
D
donglin 已提交
55

D
donglin 已提交
56 57 58 59 60 61
**示例:**
```ts
let abilityLifecycleCallback =  {
    onWindowStageCreate(ability, windowStage){
        console.log("AbilityLifecycleCallback onWindowStageCreate.");
    }
62
};
D
donglin 已提交
63
```
D
donglin 已提交
64 65 66

## AbilityLifecycleCallback.onWindowStageActive

D
fix  
donglin 已提交
67
onWindowStageActive(ability: UIAbility, windowStage: window.WindowStage): void;
D
donglin 已提交
68 69 70 71 72 73 74 75 76

注册监听应用上下文的生命周期后,在windowStage获焦时触发回调。

**系统能力**:SystemCapability.Ability.AbilityRuntime.AbilityCore

**参数:**

  | 参数名 | 类型 | 必填 | 说明 | 
  | -------- | -------- | -------- | -------- |
D
donglin 已提交
77
  | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | 是 | 当前Ability对象 |  
D
donglin 已提交
78
  | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | 是 | 当前WindowStage对象 |    
D
donglin 已提交
79

D
donglin 已提交
80 81 82 83 84 85
**示例:**
```ts
let abilityLifecycleCallback =  {
    onWindowStageActive(ability, windowStage){
        console.log("AbilityLifecycleCallback onWindowStageActive.");
    }
86
};
D
donglin 已提交
87
```
D
donglin 已提交
88 89 90

## AbilityLifecycleCallback.onWindowStageInactive

D
fix  
donglin 已提交
91
onWindowStageInactive(ability: UIAbility, windowStage: window.WindowStage): void;
D
donglin 已提交
92 93 94 95 96 97 98 99 100

注册监听应用上下文的生命周期后,在windowStage失焦时触发回调。

**系统能力**:SystemCapability.Ability.AbilityRuntime.AbilityCore

**参数:**

  | 参数名 | 类型 | 必填 | 说明 | 
  | -------- | -------- | -------- | -------- |
D
donglin 已提交
101
  | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | 是 | 当前Ability对象 |  
D
donglin 已提交
102
  | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | 是 | 当前WindowStage对象 |  
D
donglin 已提交
103

D
donglin 已提交
104 105 106 107 108 109
**示例:**
```ts
let abilityLifecycleCallback =  {
    onWindowStageInactive(ability, windowStage){
        console.log("AbilityLifecycleCallback onWindowStageInactive.");
    }
110
};
D
donglin 已提交
111
```
D
donglin 已提交
112 113 114

## AbilityLifecycleCallback.onWindowStageDestroy

D
fix  
donglin 已提交
115
onWindowStageDestroy(ability: UIAbility, windowStage: window.WindowStage): void;
D
donglin 已提交
116 117 118 119 120 121 122 123 124

注册监听应用上下文的生命周期后,在windowStage销毁时触发回调。

**系统能力**:SystemCapability.Ability.AbilityRuntime.AbilityCore

**参数:**

  | 参数名 | 类型 | 必填 | 说明 | 
  | -------- | -------- | -------- | -------- |
D
donglin 已提交
125
  | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | 是 | 当前Ability对象 |  
D
donglin 已提交
126
  | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | 是 | 当前WindowStage对象 |  
D
donglin 已提交
127

D
donglin 已提交
128 129 130 131 132 133
**示例:**
```ts
let abilityLifecycleCallback =  {
    onWindowStageDestroy(ability, windowStage){
        console.log("AbilityLifecycleCallback onWindowStageDestroy.");
    }
134
};
D
donglin 已提交
135
```
D
donglin 已提交
136 137 138

## AbilityLifecycleCallback.onAbilityDestroy

D
fix  
donglin 已提交
139
onAbilityDestroy(ability: UIAbility): void;
D
donglin 已提交
140 141 142 143 144 145 146 147 148

注册监听应用上下文的生命周期后,在ability销毁时触发回调。

**系统能力**:SystemCapability.Ability.AbilityRuntime.AbilityCore

**参数:**

  | 参数名 | 类型 | 必填 | 说明 | 
  | -------- | -------- | -------- | -------- |
D
donglin 已提交
149
  | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | 是 | 当前Ability对象 | 
D
donglin 已提交
150

D
donglin 已提交
151 152 153 154 155 156
**示例:**
```ts
let abilityLifecycleCallback =  {
    onAbilityDestroy(ability){
        console.log("AbilityLifecycleCallback onAbilityDestroy.");
    }
157
};
D
donglin 已提交
158
```
D
donglin 已提交
159 160 161

## AbilityLifecycleCallback.onAbilityForeground

D
fix  
donglin 已提交
162
onAbilityForeground(ability: UIAbility): void;
D
donglin 已提交
163 164 165 166 167 168 169 170 171

注册监听应用上下文的生命周期后,在ability的状态从后台转到前台时触发回调。

**系统能力**:SystemCapability.Ability.AbilityRuntime.AbilityCore

**参数:**

  | 参数名 | 类型 | 必填 | 说明 | 
  | -------- | -------- | -------- | -------- |
D
donglin 已提交
172
  | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | 是 | 当前Ability对象 | 
D
donglin 已提交
173

D
donglin 已提交
174 175 176 177 178 179
**示例:**
```ts
let abilityLifecycleCallback =  {
    onAbilityForeground(ability){
        console.log("AbilityLifecycleCallback onAbilityForeground.");
    }
180
};
D
donglin 已提交
181
```
D
donglin 已提交
182 183 184

## AbilityLifecycleCallback.onAbilityBackground

D
fix  
donglin 已提交
185
onAbilityBackground(ability: UIAbility): void;
D
donglin 已提交
186 187 188 189 190 191 192 193 194

注册监听应用上下文的生命周期后,在ability的状态从前台转到后台时触发回调。

**系统能力**:SystemCapability.Ability.AbilityRuntime.AbilityCore

**参数:**

  | 参数名 | 类型 | 必填 | 说明 | 
  | -------- | -------- | -------- | -------- |
D
donglin 已提交
195
  | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | 是 | 当前Ability对象 | 
D
donglin 已提交
196

D
donglin 已提交
197 198 199 200 201 202
**示例:**
```ts
let abilityLifecycleCallback =  {
    onAbilityBackground(ability){
        console.log("AbilityLifecycleCallback onAbilityBackground.");
    }
203
};
D
donglin 已提交
204
```
D
donglin 已提交
205 206 207

## AbilityLifecycleCallback.onAbilityContinue

D
fix  
donglin 已提交
208
onAbilityContinue(ability: UIAbility): void;
D
donglin 已提交
209 210 211 212 213 214 215 216 217

注册监听应用上下文的生命周期后,在ability迁移时触发回调。

**系统能力**:SystemCapability.Ability.AbilityRuntime.AbilityCore

**参数:**

  | 参数名 | 类型 | 必填 | 说明 | 
  | -------- | -------- | -------- | -------- |
D
donglin 已提交
218
  | ability | [UIAbility](js-apis-app-ability-uiAbility.md) | 是 | 当前Ability对象 | 
D
donglin 已提交
219

D
donglin 已提交
220 221 222 223 224 225
**示例:**
```ts
let abilityLifecycleCallback =  {
    onAbilityContinue(ability){
        console.log("AbilityLifecycleCallback onAbilityContinue.");
    }
226
};
D
donglin 已提交
227
```
228

D
donglin 已提交
229 230
## AbilityLifecycleCallback使用

D
donglin 已提交
231
**示例:**
D
donglin 已提交
232

D
donglin 已提交
233
MyFirstAbility.ts
D
donglin 已提交
234 235
```ts
import AbilityLifecycleCallback from "@ohos.app.ability.AbilityLifecycleCallback";
D
donglin 已提交
236 237
import AbilityStage from "@ohos.app.ability.AbilityStage";
import UIAbility from '@ohos.app.ability.UIAbility';
D
donglin 已提交
238

D
donglin 已提交
239 240
// 声明ability生命周期回调,需配置所有回调后才可以在applicationContext注册
let abilityLifecycleCallback = {
D
donglin 已提交
241
    onAbilityCreate(ability){
D
donglin 已提交
242
        console.log("AbilityLifecycleCallback onAbilityCreate.");  
D
donglin 已提交
243 244
    },
    onWindowStageCreate(ability, windowStage){
D
donglin 已提交
245
        console.log("AbilityLifecycleCallback onWindowStageCreate.");
D
donglin 已提交
246 247
    },
    onWindowStageActive(ability, windowStage){
D
donglin 已提交
248
        console.log("AbilityLifecycleCallback onWindowStageActive.");
D
donglin 已提交
249 250
    },
    onWindowStageInactive(ability, windowStage){
D
donglin 已提交
251
        console.log("AbilityLifecycleCallback onWindowStageInactive.");
D
donglin 已提交
252 253
    },
    onWindowStageDestroy(ability, windowStage){
D
donglin 已提交
254
        console.log("AbilityLifecycleCallback onWindowStageDestroy.");
D
donglin 已提交
255 256
    },
    onAbilityDestroy(ability){
D
donglin 已提交
257
        console.log("AbilityLifecycleCallback onAbilityDestroy.");
D
donglin 已提交
258 259
    },
    onAbilityForeground(ability){
D
donglin 已提交
260
        console.log("AbilityLifecycleCallback onAbilityForeground.");
D
donglin 已提交
261 262
    },
    onAbilityBackground(ability){
D
donglin 已提交
263
        console.log("AbilityLifecycleCallback onAbilityBackground.");
D
donglin 已提交
264 265
    },
    onAbilityContinue(ability){
D
donglin 已提交
266
        console.log("AbilityLifecycleCallback onAbilityContinue.");
D
donglin 已提交
267
    }
268
};
D
donglin 已提交
269

D
donglin 已提交
270
export default class MyFirstAbility extends UIAbility {
D
donglin 已提交
271
    onCreate() {
D
donglin 已提交
272
        console.log("MyAbilityStage onCreate");
D
donglin 已提交
273 274 275
        // 1.通过context属性获取applicationContext
        let applicationContext = this.context.getApplicationContext();
        // 2.通过applicationContext注册监听应用内生命周期
276
        try {
D
donglin 已提交
277
            globalThis.lifecycleId = applicationContext.on("abilityLifecycle", abilityLifecycleCallback);
278 279 280 281
            console.log("registerAbilityLifecycleCallback number: " + JSON.stringify(lifecycleId));
        } catch (paramError) {
            console.log("error: " + paramError.code + " ," + paramError.message);
        }
D
donglin 已提交
282 283 284 285
    }
}
```

D
donglin 已提交
286
MySecondAbility.ts
D
donglin 已提交
287
```ts
288
import UIAbility from "ohos.app.ability.UIAbility";
D
donglin 已提交
289

D
donglin 已提交
290
export default class MySecondAbility extends UIAbility {
D
donglin 已提交
291
    onDestroy() {
D
donglin 已提交
292 293
        let applicationContext = this.context.getApplicationContext();
        // 3.通过applicationContext注销监听应用内生命周期
D
donglin 已提交
294
        applicationContext.off("abilityLifecycle", globalThis.lifecycleId, (error) => {
D
donglin 已提交
295 296
            if (error && error.code !== 0) {
                console.log("unregisterAbilityLifecycleCallback fail, error: " + JSON.stringify(error));
D
donglin 已提交
297 298 299 300 301
            } else {
                console.log("unregisterAbilityLifecycleCallback success.");
            }
        });
    }
D
donglin 已提交
302 303
}
```