!20353 提交提供获取当前应用前后台状态机制文档说明

Merge pull request !20353 from xinking129/master

zh-cn/application-dev/reference/apis/js-apis-app-ability-applicationStateChangeCallback.md

+# @ohos.app.ability.ApplicationStateChangeCallback (ApplicationStateChangeCallback)
+
+ApplicationStateChangeCallback模块提供应用上下文ApplicationContext对当前应用前后台变化监听回调的能力，包括onApplicationForeground、onApplicationBackground方法。
+
+> **说明：**
+>
+> 本模块首批接口从API version 10 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。  
+> 本模块接口仅可在Stage模型下使用。
+
+## 导入模块
+
+```ts
+import ApplicationStateChangeCallback from '@ohos.app.ability.ApplicationStateChangeCallback';
+```
+
+## ApplicationStateChangeCallback.onApplicationForeground
+
+onApplicationForeground(): void;
+
+注册当前应用前后台变化的监听后，在当前应用从后台切换到前台时触发回调。
+
+**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore
+
+**示例：**
+
+```ts
+import UIAbility from '@ohos.app.ability.UIAbility';
+
+globalThis.applicationStateChangeCallback = {
+    onApplicationForeground() {
+        console.info('applicationStateChangeCallback onApplicationForeground');
+    }
+}
+
+export default class MyAbility extends UIAbility {
+    onCreate() {
+        console.log('MyAbility onCreate');
+        globalThis.applicationContext = this.context.getApplicationContext();
+        // 1.获取applicationContext
+        let applicationContext = globalThis.applicationContext;
+        // 2.通过applicationContext注册应用前后台状态监听
+        applicationContext.on('applicationStateChange', globalThis.ApplicationStateChangeCallback);
+    }
+    onDestroy() {
+        let applicationContext = globalThis.applicationContext;
+        // 1.通过applicationContext解除注册应用前后台状态监听
+        applicationContext.off('applicationStateChange', globalThis.ApplicationStateChangeCallback);
+    }
+}
+```
+
+## ApplicationStateChangeCallback.onApplicationBackground
+
+onApplicationBackground(): void;
+
+注册当前应用前后台变化的监听后，在当前应用从前台切换到后台时触发回调。
+
+**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore
+
+**示例：**
+
+```ts
+import UIAbility from '@ohos.app.ability.UIAbility';
+
+globalThis.applicationStateChangeCallback = {
+    onApplicationBackground() {
+        console.info('applicationStateChangeCallback onApplicationBackground');
+    }
+}
+
+export default class MyAbility extends UIAbility {
+    onCreate() {
+        console.log('MyAbility onCreate');
+        globalThis.applicationContext = this.context.getApplicationContext();
+        // 1.获取applicationContext
+        let applicationContext = globalThis.applicationContext;
+        // 2.通过applicationContext注册应用前后台状态监听
+        applicationContext.on('applicationStateChange', globalThis.ApplicationStateChangeCallback);
+        console.log('Resgiter applicationStateChangeCallback');
+    }
+    onDestroy() {
+        let applicationContext = globalThis.applicationContext;
+        // 1.通过applicationContext解除注册应用前后台状态监听
+        applicationContext.off('applicationStateChange', globalThis.ApplicationStateChangeCallback);
+    }
+}
+```
\ No newline at end of file

zh-cn/application-dev/reference/apis/js-apis-inner-application-applicationContext.md

@@ -279,6 +279,111 @@ export default class MyAbility extends Ability {
 }
 ```
 
+## ApplicationContext.on(type: 'applicationStateChange', callback: ApplicationStateChangeCallback)<sup>10+</sup>
+
+on(type: 'applicationStateChange', callback: ApplicationStateChangeCallback): **void**;
+
+注册对当前应用前后台变化的监听。使用callback异步回调。
+
+**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
+
+**参数：**
+
+| 参数名   | 类型                                                         | 必填 | 说明             |
+| -------- | ------------------------------------------------------------ | ---- | ---------------- |
+| type     | string                                     | 是   | 监听事件类型，必须为'applicationStateChange'。 |
+| callback | [ApplicationStateChangeCallback](#js-apis-app-ability-applicationStateChangeCallback.md) | 是   | 对于该事件监听的回调方法，可以对应用从后台切换到前台，以及前台切换到后台分别定义回调。       |
+
+**示例：**
+
+```ts
+import UIAbility from '@ohos.app.ability.UIAbility';
+
+export default class MyAbility extends UIAbility {
+    onCreate() {
+        console.log('MyAbility onCreate');
+        globalThis.applicationStateChangeCallback = {
+            onApplicationForeground() {
+                console.info('applicationStateChangeCallback onApplicationForeground');
+            },
+            onApplicationBackground() {
+                console.info('applicationStateChangeCallback onApplicationBackground');
+            }
+        }
+
+        globalThis.applicationContext = this.context.getApplicationContext();
+        // 1.获取applicationContext
+        let applicationContext = globalThis.applicationContext;
+        // 2.通过applicationContext注册应用前后台状态监听
+        applicationContext.on('applicationStateChange', globalThis.ApplicationStateChangeCallback);
+        console.log('Resgiter applicationStateChangeCallback');
+    }
+}
+```
+
+## ApplicationContext.off(type: 'applicationStateChange', callback: AsyncCallback\<void>)<sup>10+</sup>
+
+off(type: 'applicationStateChange', callback: AsyncCallback<**void**>): **void**;
+
+取消当前应用指定的前后台变化的监听。
+
+**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
+
+**参数：**
+
+| 参数名   | 类型                     | 必填 | 说明                             |
+| -------- | ------------------------ | ---- | -------------------------------- |
+| type     | string | 是   | 取消监听事件的类型,必须为'applicationStateChange'。             |
+| callback | AsyncCallback\<void>     | 否   | 删除指定callback对应的注册监听。 |
+
+**示例：**
+
+```ts
+import UIAbility from '@ohos.app.ability.UIAbility';
+
+export default class EntryAbility extends UIAbility {
+    onDestroy() {
+        globalThis.applicationStateChangeCallback = {
+            onApplicationForeground() {
+                console.info('applicationStateChangeCallback onApplicationForeground');
+            },
+            onApplicationBackground() {
+                console.info('applicationStateChangeCallback onApplicationBackground');
+            }
+        }
+        let applicationContext = this.context.getApplicationContext();
+        applicationContext.off('applicationStateChange', globalThis.ApplicationStateChangeCallback);
+    }
+}
+```
+
+## ApplicationContext.off(type: 'applicationStateChange')<sup>10+</sup>
+
+off(type: 'applicationStateChange'): **void**;
+
+取消当前应用注册的前后台变化的全部监听。
+
+**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
+
+**参数：**
+
+| 参数名 | 类型          | 必填 | 说明                 |
+| ------ | ------------- | ---- | -------------------- |
+| type   | string | 是   | 取消监听事件的类型,必须为'applicationStateChange'。 |
+
+**示例：**
+
+```ts
+import UIAbility from '@ohos.app.ability.UIAbility';
+
+export default class MyAbility extends UIAbility {
+    onDestroy() {
+        let applicationContext = this.context.getApplicationContext();
+        applicationContext.off('applicationStateChange');
+    }
+}
+```
+
 ## ApplicationContext.getRunningProcessInformation<sup>9+</sup>
 
 getRunningProcessInformation(): Promise\<Array\<ProcessInformation>>;

zh-cn/application-dev/reference/apis/js-apis-inner-application-processInformation.md

@@ -38,3 +38,4 @@ appManager.getRunningProcessInformation((error, data) => {
 | uid | number | 是 | 否 | 用户ID。 |
 | processName | string | 是 | 否 | 进程名称。 |
 | bundleNames | Array<string> | 是 | 否 | 进程中所有运行的Bundle名称。 |
+| state<sup>10+</sup> | [appManager.ProcessState](js-apis-app-ability-appManager.md#processstate)| 是 | 否 | 当前进程运行状态。|