1# 订阅系统环境变量的变化
2
3系统环境变量是指：在应用程序运行期间，终端设备的系统设置（例如系统的语言环境、屏幕方向等）发生变化。
4
5开发者通过订阅系统环境变化，可以使应用程序及时感知这种变化，并作出相应处理，从而提供更好的用户体验。例如，用户更改系统语言设置时，应用程序可以自动根据新的语言设置更新用户界面的语言；当用户将设备旋转到横屏或者竖屏时，应用程序可以重新布局用户界面，以适应屏幕方向和尺寸。
6
7系统配置的变化通常由“设置”中的选项或“控制中心”中的图标触发。订阅系统环境变量变化，可以使应用程序更加智能地响应系统环境变化，从而提供更好的用户体验。查看当前支持订阅变化的系统环境变量，请参见[Configuration](../reference/apis-ability-kit/js-apis-app-ability-configuration.md)。
8
9基于当前的应用模型，可以通过以下几种方式来实现订阅系统环境变量的变化。
10
11- [使用ApplicationContext订阅回调](#使用applicationcontext订阅回调)
12- [在AbilityStage组件容器中订阅回调](#在abilitystage组件容器中订阅回调)
13- [在UIAbility组件中订阅回调](#在uiability组件中订阅回调)
14- [在ExtensionAbility组件中订阅回调](#在extensionability组件中订阅回调)
15
16## 使用ApplicationContext订阅回调
17
18[ApplicationContext](../reference/apis-ability-kit/js-apis-inner-application-applicationContext.md)提供了注册回调函数以订阅系统环境变量的变化，并且可以通过调用相应的方法来撤销该回调。这有助于在资源不再需要时释放相关资源，从而提高系统的可靠性和性能。
19
201. 使用[on](../reference/apis-ability-kit/js-apis-inner-application-applicationContext.md#applicationcontextonenvironment)方法，应用程序可以通过在非应用组件模块中订阅系统环境变量的变化来动态响应这些变化。例如，使用该方法在页面中监测系统语言的变化。
21
22    ```ts
23    import { common, EnvironmentCallback, Configuration } from '@kit.AbilityKit';
24    import { hilog } from '@kit.PerformanceAnalysisKit';
25    import { BusinessError } from '@kit.BasicServicesKit';
26
27    const TAG: string = '[CollaborateAbility]';
28    const DOMAIN_NUMBER: number = 0xFF00;
29
30    @Entry
31    @Component
32    struct Index {
33      private context = getContext(this) as common.UIAbilityContext;
34      private callbackId: number = 0; // 注册订阅系统环境变化的ID
35
36      subscribeConfigurationUpdate(): void {
37        let systemLanguage: string | undefined = this.context.config.language; // 获取系统当前语言
38
39        // 1.获取ApplicationContext
40        let applicationContext = this.context.getApplicationContext();
41
42        // 2.通过applicationContext订阅环境变量变化
43        let environmentCallback: EnvironmentCallback = {
44          onConfigurationUpdated(newConfig: Configuration) {
45            hilog.info(DOMAIN_NUMBER, TAG, `onConfigurationUpdated systemLanguage is ${systemLanguage}, newConfig: ${JSON.stringify(newConfig)}`);
46            if (systemLanguage !== newConfig.language) {
47              hilog.info(DOMAIN_NUMBER, TAG, `systemLanguage from ${systemLanguage} changed to ${newConfig.language}`);
48              systemLanguage = newConfig.language; // 将变化之后的系统语言保存，作为下一次变化前的系统语言
49            }
50          },
51          onMemoryLevel(level) {
52            hilog.info(DOMAIN_NUMBER, TAG, `onMemoryLevel level: ${level}`);
53          }
54        }
55        try {
56          this.callbackId = applicationContext.on('environment', environmentCallback);
57        } catch (err) {
58          let code = (err as BusinessError).code;
59          let message = (err as BusinessError).message;
60          hilog.error(DOMAIN_NUMBER, TAG, `Failed to register applicationContext. Code is ${code}, message is ${message}`);
61        }
62      }
63
64      // 页面展示
65      build() {
66        //...
67      }
68    }
69    ```
70
712. 在资源使用完成之后，可以通过调用[off](../reference/apis-ability-kit/js-apis-inner-application-applicationContext.md#applicationcontextoffenvironment-1)方法释放相关资源。
72
73    ```ts
74    import { common } from '@kit.AbilityKit';
75    import { hilog } from '@kit.PerformanceAnalysisKit';
76    import { BusinessError } from '@kit.BasicServicesKit';
77
78    const TAG: string = '[CollaborateAbility]';
79    const DOMAIN_NUMBER: number = 0xFF00;
80
81    @Entry
82    @Component
83    struct Index {
84      private context = getContext(this) as common.UIAbilityContext;
85      private callbackId: number = 0; // 注册订阅系统环境变化的ID
86
87      unsubscribeConfigurationUpdate() {
88        let applicationContext = this.context.getApplicationContext();
89        try {
90          applicationContext.off('environment', this.callbackId);
91        } catch (err) {
92          let code = (err as BusinessError).code;
93          let message = (err as BusinessError).message;
94          hilog.error(DOMAIN_NUMBER, TAG, `Failed to unregister applicationContext. Code is ${code}, message is ${message}`);
95        }
96      }
97
98      // 页面展示
99      build() {
100        //...
101      }
102    }
103    ```
104
105## 在AbilityStage组件容器中订阅回调
106
107使用[AbilityStage.onConfigurationUpdate()](../reference/apis-ability-kit/js-apis-app-ability-abilityStage.md#abilitystageonconfigurationupdate)回调方法订阅系统环境变量的变化。当系统环境变量发生变化时，会调用该回调方法。在该方法中，通过[Configuration](../reference/apis-ability-kit/js-apis-app-ability-configuration.md)对象获取最新的系统环境配置信息。可以进行相应的界面适配等操作，从而提高系统的灵活性和可维护性。
108
109> **说明：**
110>
111> - DevEco Studio默认工程中未自动生成[AbilityStage](../reference/apis-ability-kit/js-apis-app-ability-abilityStage.md)，AbilityStage文件的创建请参见[AbilityStage组件容器](abilitystage.md)。
112> - 当使用回调方法订阅系统环境变量的变化时，该回调方法会随着AbilityStage的生命周期而存在，在Module销毁时一并销毁。
113
114例如，在[AbilityStage.onConfigurationUpdate()](../reference/apis-ability-kit/js-apis-app-ability-abilityStage.md#abilitystageonconfigurationupdate)回调方法中实现监测系统语言的变化。
115
116```ts
117import { AbilityStage, Configuration } from '@kit.AbilityKit';
118import { hilog } from '@kit.PerformanceAnalysisKit';
119
120const TAG: string = '[MyAbilityStage]';
121const DOMAIN_NUMBER: number = 0xFF00;
122
123let systemLanguage: string | undefined; // 系统当前语言
124
125export default class MyAbilityStage extends AbilityStage {
126  onCreate(): void {
127    systemLanguage = this.context.config.language; // Module首次加载时，获取系统当前语言
128    hilog.info(DOMAIN_NUMBER, TAG, `systemLanguage is ${systemLanguage}`);
129    //...
130  }
131
132  onConfigurationUpdate(newConfig: Configuration): void {
133    hilog.info(DOMAIN_NUMBER, TAG, `onConfigurationUpdate, language: ${newConfig.language}`);
134    hilog.info(DOMAIN_NUMBER, TAG, `onConfigurationUpdated systemLanguage is ${systemLanguage}, newConfig: ${JSON.stringify(newConfig)}`);
135
136    if (systemLanguage !== newConfig.language) {
137      hilog.info(DOMAIN_NUMBER, TAG, `systemLanguage from ${systemLanguage} changed to ${newConfig.language}`);
138      systemLanguage = newConfig.language; // 将变化之后的系统语言保存，作为下一次变化前的系统语言
139    }
140  }
141}
142```
143
144## 在UIAbility组件中订阅回调
145
146[UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md)组件提供了[UIAbility.onConfigurationUpdate()](../reference/apis-ability-kit/js-apis-app-ability-ability.md#abilityonconfigurationupdate)回调方法用于订阅系统环境变量的变化。当系统环境变量发生变化时，会调用该回调方法。在该方法中，通过[Configuration](../reference/apis-ability-kit/js-apis-app-ability-configuration.md)对象获取最新的系统环境配置信息，而无需重启UIAbility。
147
148> **说明：**
149>
150> 当使用回调方法订阅系统环境变量的变化时，该回调方法会随着UIAbility的生命周期而存在，在UIAbility销毁时一并销毁。
151
152例如，在[onConfigurationUpdate()](../reference/apis-ability-kit/js-apis-app-ability-ability.md#abilityonconfigurationupdate)回调方法中实现监测系统语言的变化。
153
154```ts
155import { AbilityConstant, Configuration, UIAbility, Want } from '@kit.AbilityKit';
156import { hilog } from '@kit.PerformanceAnalysisKit';
157
158const TAG: string = '[EntryAbility]';
159const DOMAIN_NUMBER: number = 0xFF00;
160
161let systemLanguage: string | undefined; // 系统当前语言
162
163export default class EntryAbility extends UIAbility {
164  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
165    systemLanguage = this.context.config.language; // UIAbility实例首次加载时，获取系统当前语言
166    hilog.info(DOMAIN_NUMBER, TAG, `systemLanguage is ${systemLanguage}`);
167  }
168
169  onConfigurationUpdate(newConfig: Configuration): void {
170    hilog.info(DOMAIN_NUMBER, TAG, `onConfigurationUpdated systemLanguage is ${systemLanguage}, newConfig: ${JSON.stringify(newConfig)}`);
171
172    if (systemLanguage !== newConfig.language) {
173      hilog.info(DOMAIN_NUMBER, TAG, `systemLanguage from ${systemLanguage} changed to ${newConfig.language}`);
174      systemLanguage = newConfig.language; // 将变化之后的系统语言保存，作为下一次变化前的系统语言
175    }
176  }
177  // ...
178}
179```
180
181## 在ExtensionAbility组件中订阅回调
182
183[ExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-extensionAbility.md)组件提供了[onConfigurationUpdate()](../reference/apis-ability-kit/js-apis-app-ability-ability.md#abilityonconfigurationupdate)回调方法用于订阅系统环境变量的变化。当系统环境变量发生变化时，会调用该回调方法。在该方法中，通过[Configuration](../reference/apis-ability-kit/js-apis-app-ability-configuration.md)对象获取最新的系统环境配置信息。
184
185> **说明：**
186>
187> 当使用回调方法订阅系统环境变量的变化时，该回调方法会随着ExtensionAbility的生命周期而存在，在ExtensionAbility销毁时一并销毁。
188
189以[FormExtensionAbility](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md)为例说明。例如，在[onConfigurationUpdate()](../reference/apis-ability-kit/js-apis-app-ability-ability.md#abilityonconfigurationupdate)回调方法中实现系统环境变量的变化。
190
191```ts
192import { FormExtensionAbility } from '@kit.FormKit';
193import { Configuration } from '@kit.AbilityKit';
194import { hilog } from '@kit.PerformanceAnalysisKit';
195
196const TAG: string = '[EntryAbility]';
197const DOMAIN_NUMBER: number = 0xFF00;
198
199export default class EntryFormAbility extends FormExtensionAbility {
200  onConfigurationUpdate(config: Configuration) {
201    hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] onConfigurationUpdate:' + JSON.stringify(config));
202  }
203  // ...
204}
205```
206