HarmonyOS Next开发学习手册——订阅系统环境变量的变化

系统环境变量是指：在应用程序运行期间，终端设备的系统设置（例如系统的语言环境、屏幕方向等）发生变化。

开发者通过订阅系统环境变化，可以使应用程序及时感知这种变化，并作出相应处理，从而提供更好的用户体验。例如，用户更改系统语言设置时，应用程序可以自动根据新的语言设置更新用户界面的语言；当用户将设备旋转到横屏或者竖屏时，应用程序可以重新布局用户界面，以适应屏幕方向和尺寸。

系统配置的变化通常由“设置”中的选项或“控制中心”中的图标触发。订阅系统环境变量变化，可以使应用程序更加智能地响应系统环境变化，从而提供更好的用户体验。查看当前支持订阅变化的系统环境变量，请参见 Configuration 。

基于当前的应用模型，可以通过以下几种方式来实现订阅系统环境变量的变化。

• 使用ApplicationContext订阅回调
• 在AbilityStage组件容器中订阅回调
• 在UIAbility组件中订阅回调
• 在ExtensionAbility组件中订阅回调

使用ApplicationContext订阅回调

ApplicationContext 提供了注册回调函数以订阅系统环境变量的变化，并且可以通过调用相应的方法来撤销该回调。这有助于在资源不再需要时释放相关资源，从而提高系统的可靠性和性能。

1. 使用ApplicationContext.on(type: ‘environment’, callback: EnvironmentCallback)方法，应用程序可以通过在非应用组件模块中订阅系统环境变量的变化来动态响应这些变化。例如，使用该方法在页面中监测系统语言的变化。

import { common, EnvironmentCallback, Configuration } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

const TAG: string = '[CollaborateAbility]';
const DOMAIN_NUMBER: number = 0xFF00;

@Entry
@Component
struct Index {
  private context = getContext(this) as common.UIAbilityContext;
  private callbackId: number = 0; // 注册订阅系统环境变化的ID

  subscribeConfigurationUpdate(): void {
    let systemLanguage: string | undefined = this.context.config.language; // 获取系统当前语言

    // 1.获取ApplicationContext
    let applicationContext = this.context.getApplicationContext();

    // 2.通过applicationContext订阅环境变量变化
    let environmentCallback: EnvironmentCallback = {
      onConfigurationUpdated(newConfig: Configuration) {
        hilog.info(DOMAIN_NUMBER, TAG, `onConfigurationUpdated systemLanguage is ${systemLanguage}, newConfig: ${JSON.stringify(newConfig)}`);
        if (this.systemLanguage !== newConfig.language) {
          hilog.info(DOMAIN_NUMBER, TAG, `systemLanguage from ${systemLanguage} changed to ${newConfig.language}`);
          systemLanguage = newConfig.language; // 将变化之后的系统语言保存，作为下一次变化前的系统语言
        }
      },
      onMemoryLevel(level) {
        hilog.info(DOMAIN_NUMBER, TAG, `onMemoryLevel level: ${level}`);
      }
    }
    try {
      this.callbackId = applicationContext.on('environment', environmentCallback);
    } catch (err) {
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      hilog.error(DOMAIN_NUMBER, TAG, `Failed to register applicationContext. Code is ${code}, message is ${message}`);
    };
  }

  // 页面展示
  build() {
    //...
  }
}

1. 在资源使用完成之后，可以通过调用ApplicationContext.off(type: ‘environment’, callbackId: number)方法释放相关资源。

import { common } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  private context = getContext(this) as common.UIAbilityContext;
  private callbackId: number = 0; // 注册订阅系统环境变化的ID

  unsubscribeConfigurationUpdate() {
    let applicationContext = this.context.getApplicationContext();
    applicationContext.off('environment', this.callbackId);
  }

  // 页面展示
  build() {
    //...
  }
}

在AbilityStage组件容器中订阅回调

使用 AbilityStage.onConfigurationUpdate() 回调方法订阅系统环境变量的变化。当系统环境变量发生变化时，会调用该回调方法。在该方法中，通过 Configuration 对象获取最新的系统环境配置信息。可以进行相应的界面适配等操作，从而提高系统的灵活性和可维护性。

说明

• DevEco Studio默认工程中未自动生成AbilityStage，AbilityStage文件的创建请参见 AbilityStage组件容器 。
• 当使用回调方法订阅系统环境变量的变化时，该回调方法会随着 AbilityStage 的生命周期而存在，在Module销毁时一并销毁。

例如，在 AbilityStage.onConfigurationUpdate() 回调方法中实现监测系统语言的变化。

import { AbilityStage, Configuration } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = '[MyAbilityStage]';
const DOMAIN_NUMBER: number = 0xFF00;

let systemLanguage: string | undefined; // 系统当前语言

export default class MyAbilityStage extends AbilityStage {
  onCreate(): void {
    systemLanguage = this.context.config.language; // Module首次加载时，获取系统当前语言
    hilog.info(DOMAIN_NUMBER, TAG, `systemLanguage is ${systemLanguage}`);
    //...
  }

  onConfigurationUpdate(newConfig: Configuration): void {
    hilog.info(DOMAIN_NUMBER, TAG, `onConfigurationUpdate, language: ${newConfig.language}`);
    hilog.info(DOMAIN_NUMBER, TAG, `onConfigurationUpdated systemLanguage is ${systemLanguage}, newConfig: ${JSON.stringify(newConfig)}`);

    if (systemLanguage !== newConfig.language) {
      hilog.info(DOMAIN_NUMBER, TAG, `systemLanguage from ${systemLanguage} changed to ${newConfig.language}`);
      systemLanguage = newConfig.language; // 将变化之后的系统语言保存，作为下一次变化前的系统语言
    }
  }
}

在UIAbility组件中订阅回调

UIAbility组件提供了UIAbility.onConfigurationUpdate()回调方法用于订阅系统环境变量的变化。当系统环境变量发生变化时，会调用该回调方法。在该方法中，通过 Configuration 对象获取最新的系统环境配置信息，而无需重启UIAbility。

说明
当使用回调方法订阅系统环境变量的变化时，该回调方法会随着UIAbility的生命周期而存在，在UIAbility销毁时一并销毁。

例如，在onConfigurationUpdate()回调方法中实现监测系统语言的变化。

import { AbilityConstant, Configuration, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = '[EntryAbility]';
const DOMAIN_NUMBER: number = 0xFF00;

let systemLanguage: string | undefined; // 系统当前语言

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    systemLanguage = this.context.config.language; // UIAbility实例首次加载时，获取系统当前语言
    hilog.info(DOMAIN_NUMBER, TAG, `systemLanguage is ${systemLanguage}`);
  }

  onConfigurationUpdate(newConfig: Configuration): void {
    hilog.info(DOMAIN_NUMBER, TAG, `onConfigurationUpdated systemLanguage is ${systemLanguage}, newConfig: ${JSON.stringify(newConfig)}`);

    if (systemLanguage !== newConfig.language) {
      hilog.info(DOMAIN_NUMBER, TAG, `systemLanguage from ${systemLanguage} changed to ${newConfig.language}`);
      systemLanguage = newConfig.language; // 将变化之后的系统语言保存，作为下一次变化前的系统语言
    }
  }

  // ...
}

在ExtensionAbility组件中订阅回调

ExtensionAbility组件提供了onConfigurationUpdate()回调方法用于订阅系统环境变量的变化。当系统环境变量发生变化时，会调用该回调方法。在该方法中，通过 Configuration 对象获取最新的系统环境配置信息。

说明
当使用回调方法订阅系统环境变量的变化时，该回调方法会随着ExtensionAbility的生命周期而存在，在ExtensionAbility销毁时一并销毁。

以FormExtensionAbility为例说明。例如，在onConfigurationUpdate()回调方法中实现系统环境变量的变化。

import { FormExtensionAbility } from '@kit.FormKit';
import { Configuration } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = '[EntryAbility]';
const DOMAIN_NUMBER: number = 0xFF00;

export default class EntryFormAbility extends FormExtensionAbility {
  onConfigurationUpdate(config: Configuration) {
    hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] onConfigurationUpdate:' + JSON.stringify(config));
  }
  // ...
}

鸿蒙全栈开发全新学习指南

也为了积极培养鸿蒙生态人才，让大家都能学习到鸿蒙开发最新的技术，针对一些在职人员、0基础小白、应届生/计算机专业、鸿蒙爱好者等人群，整理了一套纯血版鸿蒙（HarmonyOS Next）全栈开发技术的学习路线【包含了大厂APP实战项目开发】。

本路线共分为四个阶段：

第一阶段：鸿蒙初中级开发必备技能

第二阶段：鸿蒙南北双向高工技能基础：gitee.com/MNxiaona/733GH

第三阶段：应用开发中高级就业技术

第四阶段：全网首发-工业级南向设备开发就业技术：gitee.com/MNxiaona/733GH

鸿蒙开发面试真题（含参考答案）:gitee.com/MNxiaona/733GH

写在最后

• 如果你觉得这篇内容对你还蛮有帮助，我想邀请你帮我三个小忙：
• 点赞，转发，有你们的 『点赞和评论』，才是我创造的动力。
• 关注小编，同时可以期待后续文章ing🚀，不定期分享原创知识。
• 想要获取更多完整鸿蒙最新学习资源，请移步前往小编：gitee.com/MNxiaona/733GH