harmony 鸿蒙Environment：设备环境查询

2025-06-16
浏览 (3)

Environment：设备环境查询

如果开发者需要获取应用程序运行设备的环境参数（如多语言、深浅色模式等）以进行不同的场景判断，可以使用Environment设备环境查询。

Environment是ArkUI框架在应用程序启动时创建的单例对象，为AppStorage提供应用程序运行状态的属性。所有属性都是不可变的简单类型。

Environment提供了读取系统环境变量并将其值写入AppStorage的功能。开发者需要通过AppStorage获取环境变量的值。详细信息请参阅 Environment 内置参数。

在阅读本文档前，建议提前阅读：AppStorage。

Environment内置参数

键	数据类型	描述
accessibilityEnabled	boolean	是否启用获取无障碍屏幕读取。true表示启用，false表示不启用。
colorMode	ColorMode	色彩模型类型。 - ColorMode.LIGHT：浅色。 - ColorMode.DARK：深色。
fontScale	number	字体大小比例。开发者需要配置configuration，设置fontSizeScale为”followSystem”，具体配置步骤可参考configuration使fontScale跟随系统变化。默认值跟随系统默认参数。
fontWeightScale	number	字体粗细程度。在不同的系统或者机型中，fontWeightScale的取值范围可能会有所不同。默认值跟随系统默认参数。
layoutDirection	LayoutDirection	布局方向类型： - LayoutDirection.LTR：从左到右。 - LayoutDirection.RTL：从右到左。
languageCode	string	当前系统语言值，取值必须为小写字母（例如：zh）。默认值跟随系统默认参数。

使用场景

从UI中访问Environment参数

使用Environment.envProp将设备运行的环境变量存入AppStorage中。

  // 将设备的语言code存入AppStorage，默认值为en
  Environment.envProp('languageCode', 'en');

可以使用\@StorageProp链接到Component中。

  @StorageProp('languageCode') lang: string = 'en';

设备环境到Component的更新链：Environment –> AppStorage –> Component。

说明：

\@StorageProp关联的环境参数可以在本地更改，但不能同步回AppStorage中，因为应用对环境变量参数是不可写的，只能在Environment中查询。

// 将设备languageCode存入AppStorage中
Environment.envProp('languageCode', 'en');

@Entry
@Component
struct Index {
  @StorageProp('languageCode') languageCode: string = 'en';

  build() {
    Row() {
      Column() {
        // 输出当前设备的languageCode
        Text(this.languageCode)
      }
    }
  }
}

应用逻辑使用Environment

// 使用Environment.envProp将设备运行languageCode存入AppStorage中；
Environment.envProp('languageCode', 'en');
// 从AppStorage获取单向绑定的languageCode的变量
const lang: SubscribedAbstractProperty<string> = AppStorage.prop('languageCode');

if (lang.get() === 'zh') {
  console.info('你好');
} else {
  console.info('Hello!');
}

限制条件

Environment和UIContext相关联，需要在UIContext明确的时候才可以调用。可以通过在runScopedTask里明确上下文。如果没有在UIContext明确的地方调用，将导致无法查询到设备环境数据。

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    windowStage.loadContent('pages/Index');
    let window = windowStage.getMainWindow()
    window.then(window => {
      let uicontext = window.getUIContext()
      uicontext.runScopedTask(() => {
        Environment.envProp('languageCode', 'en');
      })
    })
  }
}