62accf1c创建于 2025年6月24日历史提交

获取/设置环境变量

基本概念

环境变量包含系统环境变量和应用环境变量。

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

通常条件下，应用环境变量与系统环境变量保持一致。开发者可以通过设置应用环境变量的方式，使当前应用的环境变量与系统环境变量相互独立。

使用场景

获取应用环境变量：开发者可以通过getConfigurationSync主动获取当前应用的环境变量，以进行相关处理。例如，应用运行过程中，可以主动获取当前应用深浅色模式，以更新用户界面显示。
设置应用环境变量：针对字体大小、深浅色模式、应用语言等应用环境变量，开发者可以通过相关接口进行设置。
订阅系统环境变量：开发者可以主动订阅系统环境变量，及时感知系统状态的变化，并做出相应处理。例如，当用户将设备旋转到横屏或者竖屏时，应用可以重新布局用户界面，以适应屏幕方向和尺寸。查看当前支持订阅变化的系统环境变量，请参见Configuration。

约束限制

当应用通过接口设置应用自身环境变量后，将无法订阅对应的系统环境变量。
当系统环境变量不跟随系统变化（即configuration标签中的对应字段取值为“nonFollowSystem”）时，将无法订阅对应的系统环境变量。

获取应用环境变量

开发者可以使用getConfigurationSync主动获取当前应用环境变量，包括深浅色模式、屏幕方向、语言地区、屏幕密度、设备类型等，对应用程序作出相应处理，提供更好的用户体验。

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

export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  try {
    let value = this.context.resourceManager.getConfigurationSync();
    // 屏幕方向
    let direction = value.direction;
    // 语言文字国家地区
    let locale = value.locale;
  } catch (error) {
    console.error("getConfigurationSync error is " + error);
  }
}
}

设置应用环境变量

支持设置的应用环境变量包括字体大小、深浅色模式、应用语言，其他环境变量（例如屏幕方向等）均不支持直接设置。

设置字体大小

应用字体大小默认不跟随系统变化，开发者可以通过将configuration标签中fontSizeScale的值配置为nonFollowSystem，使得应用字体大小跟随系统变化。

开发者可以使用setFontSizeScale设置应用字体大小。设置后，应用字体将不跟随系统变化，不再支持订阅系统字体大小变化。

```ts
import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';

export default class MyAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    windowStage.loadContent('pages/Index', (err, data) => {
      if (err.code) {
        return;
      }
    });
    let applicationContext = this.context.getApplicationContext();
    applicationContext.setFontSizeScale(2);
  }
}
```

设置深浅色模式

应用深浅色模式默认跟随系统。开发者可以自定义应用或组件的深浅色模式。

配置生效的优先级为：UIAbility的深浅色模式 > 应用的深浅色模式 > 系统的深浅色模式。

设置应用的深浅色模式： 使用ApplicationContext的setColorMode接口，可以设置应用深浅色模式。

import { UIAbility, ConfigurationConstant } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';

export default class MyAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    windowStage.loadContent('pages/Index', (err, data) => {
      if (err.code) {
        hilog.error(0x0000, 'testTag', 'Failed to load the content.');
        return;
      }
      let applicationContext = this.context.getApplicationContext();
      applicationContext.setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_DARK);
    });
  }
}

设置UIAbility的深浅色模式： 使用UIAbilityContext的setColorMode，可以设置UIAbility的深浅色模式。

import { UIAbility, ConfigurationConstant } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';

export default class MyAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    windowStage.loadContent('pages/Index', (err, data) => {
      if (err.code) {
        hilog.error(0x0000, 'testTag', 'Failed to load the content.');
        return;
      }
      let uiAbilityContext = this.context;
      uiAbilityContext.setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_DARK);
    });
  }
}

设置应用语言

应用语言默认跟随系统语言变化。开发者可以使用setLanguage设置应用语言。设置后，不再支持订阅系统语言变化。

import { UIAbility } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';

export default class MyAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    windowStage.loadContent('pages/Index', (err, data) => {
      if (err.code) {
        hilog.error(0x0000, 'testTag', 'Failed to load the content.');
        return;
      }
      let applicationContext = this.context.getApplicationContext();
      applicationContext.setLanguage('zh-cn');
    });
  }
}

订阅系统环境变量

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

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

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

使用ApplicationContext订阅回调

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

使用on方法，应用程序可以通过在非应用组件模块中订阅系统环境变量的变化来动态响应这些变化。例如，使用该方法在页面中监测系统语言的变化。

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 = this.getUIContext().getHostContext() 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 (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() {
    //...
  }
}

在资源使用完成之后，可以通过调用off方法释放相关资源。

import { common } 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 = this.getUIContext().getHostContext() as common.UIAbilityContext;
  private callbackId: number = 0; // 注册订阅系统环境变化的ID

  unsubscribeConfigurationUpdate() {
    let applicationContext = this.context.getApplicationContext();
    try {
      applicationContext.off('environment', this.callbackId);
    } catch (err) {
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      hilog.error(DOMAIN_NUMBER, TAG, `Failed to unregister applicationContext. Code is ${code}, message is ${message}`);
    }
  }

  // 页面展示
  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销毁时一并销毁。

如果使用该接口监听屏幕方向变化，需要在module.json5配置文件的abilities标签中将orientation字段配置为auto_rotation。

例如，在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));
  }
  // ...
}