• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.app.ability.ApplicationStateChangeCallback (应用进程状态变化监听器)
2<!--Kit: Ability Kit-->
3<!--Subsystem: Ability-->
4<!--Owner: @SKY2001-->
5<!--Designer: @yzkp-->
6<!--Tester: @lixueqing513-->
7<!--Adviser: @huipeizi-->
8
9本模块用于监听当前应用进程的状态变化。为了便于表述，下文中将“应用进程”简称为“进程”。
10
11开发者可调用[ApplicationContext.on('applicationStateChange')](js-apis-inner-application-applicationContext.md#applicationcontextonapplicationstatechange10)方法传入自定义ApplicationStateChangeCallback来监听当前进程的前后台状态变化，从而根据进程前后台状态变化来执行某些操作。例如，统计进程前后台时长、或者当进程退到后台时清理内存缓存。
12
13> **说明：**
14>
15> 本模块首批接口从API version 10 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
16>
17> 本模块接口仅可在Stage模型下使用。
18
19## 约束限制
20
21该模块仅支持监听当前进程的前后台状态变化。如果需要监听整个应用的前后台状态变化，可使用[ApplicationStateObserver.onForegroundApplicationChanged](js-apis-inner-application-applicationStateObserver.md#applicationstateobserveronforegroundapplicationchanged)。
22
23>**说明**
24>
25> 进程的前后台状态不同于应用的前后台状态，两者的差别如下：
26>- 进程的前后台状态：如果进程中存在任何前台状态的UIAbility/UIExtensionAbility或可见窗口，则认为进程状态为前台，反之为后台。
27>- 应用的前后台状态：如果应用下有任何一个进程状态为前台，则认为应用状态为前台，反之为后台。
28
29## 导入模块
30
31```ts
32import { ApplicationStateChangeCallback } from '@kit.AbilityKit';
33```
34
35## ApplicationStateChangeCallback.onApplicationForeground
36
37onApplicationForeground(): void
38
39当前进程从后台切换到前台时触发回调。当该回调触发时，并不表示进程已完全处于前台状态，而是即将进入前台状态，此时无法执行需要依赖前台状态的操作（例如启动其他UIAbility）。
40
41**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。
42
43**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore
44
45**示例：**
46
47参见[onApplicationBackground](#applicationstatechangecallbackonapplicationbackground)。
48
49## ApplicationStateChangeCallback.onApplicationBackground
50
51onApplicationBackground(): void
52
53当前进程从前台切换到后台时触发回调。当该回调触发时，表示进程已完全处于后台状态，可以执行适合在后台状态下完成的操作（例如清理内存缓存）。
54
55**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。
56
57**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore
58
59**示例：**
60
61```ts
62import { UIAbility, ApplicationStateChangeCallback } from '@kit.AbilityKit';
63import { BusinessError } from '@kit.BasicServicesKit';
64
65let applicationStateChangeCallback: ApplicationStateChangeCallback = {
66  onApplicationForeground() {
67    console.info('applicationStateChangeCallback onApplicationForeground');
68  },
69  onApplicationBackground() {
70    console.info('applicationStateChangeCallback onApplicationBackground');
71  }
72};
73
74export default class MyAbility extends UIAbility {
75  onCreate() {
76    console.log('MyAbility onCreate');
77    // 1.获取applicationContext
78    let applicationContext = this.context.getApplicationContext();
79    try {
80      // 2.通过applicationContext注册当前进程状态监听
81      if (applicationContext != undefined) {
82        applicationContext.on('applicationStateChange', applicationStateChangeCallback);
83      }
84    } catch (paramError) {
85      console.error(`error: ${(paramError as BusinessError).code}, ${(paramError as BusinessError).message}`);
86    }
87    console.log('Register applicationStateChangeCallback');
88  }
89  onDestroy() {
90    let applicationContext = this.context.getApplicationContext();
91    try {
92      // 1.通过applicationContext解除注册当前进程状态监听
93      if (applicationContext != undefined) {
94        applicationContext.off('applicationStateChange', applicationStateChangeCallback);
95      }
96    } catch (paramError) {
97      console.error(`error: ${(paramError as BusinessError).code}, ${(paramError as BusinessError).message}`);
98    }
99  }
100}
101```
102