@Env：环境变量-响应式环境变量-ArkTS组件-ArkUI（方舟UI框架）-应用框架

@Env

Phone22+PC/2in122+Tablet22+TV22+Wearable22+

Env<T>(key: SystemEnvKey<T> | SystemProperties): PropertyDecorator

用于获取系统环境变量。API版本26.0.0之前仅支持传入SystemProperties枚举，API版本26.0.0及以后版本支持传入SystemEnvKey<T>类或SystemProperties枚举作为参数。

模型约束：此接口仅可在Stage模型下使用。

元服务API： 从API version 22开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开

参数名	类型	必填	说明
key	SystemEnvKey<T> \| SystemProperties	是	环境变量key。

返回值：

展开

类型	说明
PropertyDecorator	属性装饰器，开发者无需关注该返回值。

示例：

import { uiObserver } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  // @Env读取系统环境变量
  @Env(SystemProperties.BREAK_POINT) breakpoint: uiObserver.WindowSizeLayoutBreakpointInfo;

  build() {
    Column() {
        Text(`breakpoint height ${this.breakpoint.heightBreakpoint}`)
        Text(`breakpoint width ${this.breakpoint.widthBreakpoint}`)
    }
  }
}

EnvDecorator

type EnvDecorator = (value: SystemProperties) => PropertyDecorator

定义EnvDecorator属性装饰器类型。

模型约束：此接口仅可在Stage模型下使用。

元服务API： 从API version 22开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开

参数名	类型	必填	说明
value	SystemProperties	是	环境变量属性名，用于指定要获取的系统环境变量。

返回值：

展开

类型	说明
PropertyDecorator	属性装饰器，开发者无需关注该返回值。

错误码：

详细介绍请参见环境变量错误码。

展开

错误码ID	错误信息
140000	Invalid key for @Env

SystemProperties

Phone22+PC/2in122+Tablet22+TV22+Wearable22+

定义环境变量枚举值，用于通过@Env装饰器获取系统环境变量。

系统能力： SystemCapability.ArkUI.ArkUI.Full

展开

名称	值	说明
BREAK_POINT	'system.arkui.breakpoint'	@Env变量参数，通过@Env(SystemProperties.BREAK_POINT)可获取WindowSizeLayoutBreakpointInfo实例。当该装饰器声明在@Component或@ComponentV2中时，用于获取当前自定义组件所在窗口的尺寸布局断点信息。元服务API：从API version 22开始，该接口支持在元服务中使用。模型约束：此接口仅可在Stage模型下使用。
WINDOW_SIZE²³⁺	'system.window.size'	@Env变量参数，通过@Env(SystemProperties.WINDOW_SIZE)可获取SizeInVP实例。当该装饰器声明在@Component或@ComponentV2中时，用于获取当前自定义组件所在窗口的大小信息，单位为vp。元服务API：从API版本26.0.0开始，该接口支持在元服务中使用。模型约束：此接口仅可在Stage模型下使用。
WINDOW_SIZE_PX²³⁺	'system.window.size.px'	@Env变量参数，通过@Env(SystemProperties.WINDOW_SIZE_PX)可获取Size实例。当该装饰器声明在@Component或@ComponentV2中时，用于获取当前自定义组件所在窗口的大小信息，单位为px。元服务API：从API版本26.0.0开始，该接口支持在元服务中使用。模型约束：此接口仅可在Stage模型下使用。
WINDOW_AVOID_AREA²³⁺	'system.window.avoidarea'	@Env变量参数，通过@Env(SystemProperties.WINDOW_AVOID_AREA)可获取UIEnvWindowAvoidAreaInfoVP实例。当该装饰器声明在@Component或@ComponentV2中时，用于获取当前自定义组件所在窗口的避让区域信息，单位为vp。元服务API：从API版本26.0.0开始，该接口支持在元服务中使用。模型约束：此接口仅可在Stage模型下使用。
WINDOW_AVOID_AREA_PX²³⁺	'system.window.avoidarea.px'	@Env变量参数，通过@Env(SystemProperties.WINDOW_AVOID_AREA_PX)可获取UIEnvWindowAvoidAreaInfoPX实例。当该装饰器声明在@Component或@ComponentV2中时，用于获取当前自定义组件所在窗口的避让区域信息，单位为px。元服务API：从API版本26.0.0开始，该接口支持在元服务中使用。模型约束：此接口仅可在Stage模型下使用。

SystemEnvKey<T>

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

系统环境变量Key对应的类型。

属性

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从API版本26.0.0开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

展开

名称	类型	只读	可选	说明
type	T	否	是	系统环境变量Key对应值的数据类型，默认值为undefined。

constructor

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

protected constructor()

用于创建该类的实例对象。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从API版本26.0.0开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

WritableSystemEnvKey<T>

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

定义可写的系统环境变量Key，继承自SystemEnvKey<T>。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从API版本26.0.0开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

ReadonlySystemEnvKey<T>

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

定义只读的系统环境变量Key，继承自SystemEnvKey<T>。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从API版本26.0.0开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

WritableEnvKey

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

定义可写的系统环境变量Key集合，用于通过@Env装饰器获取对应的系统环境变量。可通过WithEnv中的env方法设置局部环境变量值以影响后代组件渲染，具体示例请参见示例2（设置局部布局方向）。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从API版本26.0.0开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

展开

名称	类型	只读	可选	说明
DIRECTION	WritableSystemEnvKey<Direction>	是	否	@Env变量参数，通过@Env(WritableEnvKey.DIRECTION)可获取Direction枚举类型的值。当该装饰器声明在@Component或@ComponentV2中时，用于获取窗口所在屏幕的布局方向。
FONT_SCALE	WritableSystemEnvKey<number>	是	否	@Env变量参数，通过@Env(WritableEnvKey.FONT_SCALE)可获取number类型的值，取值无上限，小于等于0的值按0处理。当该装饰器声明在@Component或@ComponentV2中时，用于为后代组件提供局部字体缩放倍数。

名称

类型

只读

可选

说明

DIRECTION

WritableSystemEnvKey<Direction>

是

否

@Env变量参数，通过@Env(WritableEnvKey.DIRECTION)可获取Direction枚举类型的值。

当该装饰器声明在@Component或@ComponentV2中时，用于获取窗口所在屏幕的布局方向。

FONT_SCALE

WritableSystemEnvKey<number>

是

否

@Env变量参数，通过@Env(WritableEnvKey.FONT_SCALE)可获取number类型的值，取值无上限，小于等于0的值按0处理。

当该装饰器声明在@Component或@ComponentV2中时，用于为后代组件提供局部字体缩放倍数。

ReadonlyEnvKey

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

定义只读的系统环境变量key集合，用于通过@Env装饰器获取对应的系统环境变量。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从API版本26.0.0开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

属性

展开

名称	类型	只读	可选	说明
WINDOW_AVOID_AREA	ReadonlySystemEnvKey<window.UIEnvWindowAvoidAreaInfoVP>	是	否	@Env变量参数，通过@Env(ReadonlyEnvKey.WINDOW_AVOID_AREA)可获取UIEnvWindowAvoidAreaInfoVP实例。当该装饰器声明在@Component或@ComponentV2中时，用于获取当前自定义组件所在窗口的避让区域信息，单位为vp。起始版本： 26.0.0 元服务API：从API版本26.0.0开始，该接口支持在元服务中使用。模型约束：此接口仅可在Stage模型下使用。
WINDOW_AVOID_AREA_PX	ReadonlySystemEnvKey<window.UIEnvWindowAvoidAreaInfoPX>	是	否	@Env变量参数，通过@Env(ReadonlyEnvKey.WINDOW_AVOID_AREA_PX)可获取UIEnvWindowAvoidAreaInfoPX实例。当该装饰器声明在@Component或@ComponentV2中时，用于获取当前自定义组件所在窗口的避让区域信息，单位为px。起始版本： 26.0.0 元服务API：从API版本26.0.0开始，该接口支持在元服务中使用。模型约束：此接口仅可在Stage模型下使用。
WINDOW_SIZE	ReadonlySystemEnvKey<window.SizeInVP>	是	否	@Env变量参数，通过@Env(ReadonlyEnvKey.WINDOW_SIZE)可获取SizeInVP实例。当该装饰器声明在@Component或@ComponentV2中时，用于获取当前自定义组件所在窗口的大小信息，单位为vp。起始版本： 26.0.0 元服务API：从API版本26.0.0开始，该接口支持在元服务中使用。模型约束：此接口仅可在Stage模型下使用。
WINDOW_SIZE_PX	ReadonlySystemEnvKey<window.Size>	是	否	@Env变量参数，通过@Env(ReadonlyEnvKey.WINDOW_SIZE_PX)可获取Size实例。当该装饰器声明在@Component或@ComponentV2中时，用于获取当前自定义组件所在窗口的大小信息，单位为px。起始版本： 26.0.0 元服务API：从API版本26.0.0开始，该接口支持在元服务中使用。模型约束：此接口仅可在Stage模型下使用。
WINDOW_DISPLAY_ID	ReadonlySystemEnvKey<number>	是	否	@Env变量参数，通过@Env(ReadonlyEnvKey.WINDOW_DISPLAY_ID)可获取number类型的值。当该装饰器声明在@Component或@ComponentV2中时，用于获取当前自定义组件所在窗口的屏幕ID。起始版本： 26.0.0 元服务API：从API版本26.0.0开始，该接口支持在元服务中使用。模型约束：此接口仅可在Stage模型下使用。
WINDOW_SYSTEM_DENSITY	ReadonlySystemEnvKey<number>	是	否	@Env变量参数，通过@Env(ReadonlyEnvKey.WINDOW_SYSTEM_DENSITY)可获取number类型的值。当该装饰器声明在@Component或@ComponentV2中时，用于获取当前自定义组件所在窗口的系统显示大小缩放系数。该参数为浮点数，取值范围为[0.5, 4.0]或-1.0。4.0表示窗口可显示的最大显示大小缩放系数，-1.0表示窗口使用系统显示大小缩放系数。起始版本： 26.0.0 元服务API：从API版本26.0.0开始，该接口支持在元服务中使用。模型约束：此接口仅可在Stage模型下使用。
WINDOW_IS_FOCUSED	ReadonlySystemEnvKey<boolean>	是	否	@Env变量参数，通过@Env(ReadonlyEnvKey.WINDOW_IS_FOCUSED)可获取boolean类型的值。当该装饰器声明在@Component或@ComponentV2中时，用于获取当前自定义组件所在窗口是否处于获焦状态，true表示当前处于获焦状态，false表示当前不处于获焦状态。起始版本： 26.0.0 模型约束：此接口仅可在Stage模型下使用。
WINDOW_IS_HIGHLIGHTED	ReadonlySystemEnvKey<boolean>	是	否	@Env变量参数，通过@Env(ReadonlyEnvKey.WINDOW_IS_HIGHLIGHTED)可获取boolean类型的值。当该装饰器声明在@Component或@ComponentV2中时，用于获取当前自定义组件所在窗口是否处于高亮状态，true表示当前处于高亮状态，false表示当前不处于高亮状态。起始版本： 26.0.0 模型约束：此接口仅可在Stage模型下使用。