WithEnv组件用于为子组件树设置局部环境变量作用域。开发者可以通过该组件为后代组件提供自定义环境变量,或设置系统环境变量。
起始版本: 26.0.0
WithEnv()
设置局部环境变量作用域容器。
起始版本: 26.0.0
元服务API: 从API版本26.0.0开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
模型约束:此接口仅可在Stage模型下使用。
env<T>(key: WritableSystemEnvKey<T>, value: T)
设置作用域内的系统环境变量。当前正式支持的系统环境变量键为WritableEnvKey.FONT_SCALE、WritableEnvKey.DIRECTION。
起始版本: 26.0.0
元服务API: 从API版本26.0.0开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
模型约束:此接口仅可在Stage模型下使用。
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | WritableSystemEnvKey<T> | 是 | 系统环境变量键。当前正式支持WritableEnvKey.FONT_SCALE和WritableEnvKey.DIRECTION。 |
| value | T | 是 | 系统环境变量值。value的类型T对应WritableSystemEnvKey<T>中的类型T。当key为WritableEnvKey.FONT_SCALE时,value类型为number。当key为WritableEnvKey.DIRECTION时,value类型为Direction。 |
customEnv<T>(key: CustomEnvKey<T>, value: T)
设置作用域内可被后代自定义组件读取的自定义环境变量。
起始版本: 26.0.0
元服务API: 从API版本26.0.0开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
模型约束:此接口仅可在Stage模型下使用。
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | CustomEnvKey<T> | 是 | 自定义环境变量的键。 |
| value | T | 是 | 自定义环境变量的值。value的类型T对应CustomEnvKey<T>的类型T。 |
该示例通过env(WritableEnvKey.FONT_SCALE, value)为作用域内组件设置局部字体缩放比例。
从API版本26.0.0开始,新增env属性和键值WritableEnvKey.FONT_SCALE。
// xxx.ets
import { WithEnv } from '@kit.ArkUI';
@Entry
@Component
struct WithEnvExample1 {
@State fontScale: number = 1.0;
build() {
Column({ space: 12 }) {
Row({ space: 8 }) {
Button('缩小 0.5x')
.onClick(() => {
this.fontScale = 0.5;
})
Button('正常 1.0x')
.onClick(() => {
this.fontScale = 1.0;
})
Button('放大 1.5x')
.onClick(() => {
this.fontScale = 1.5;
})
}
WithEnv() {
Column({ space: 8 }) {
Text('当前字体缩放作用域内的文本')
.fontSize(16)
Text('该文本同样受 WithEnv 字体缩放影响')
.fontSize(14)
.fontColor('#99182431')
}
.width('100%')
.alignItems(HorizontalAlign.Start)
}
.env(WritableEnvKey.FONT_SCALE, this.fontScale) // 设置局部字体缩放比例
}
.padding(12)
.width('100%')
}
} 
该示例通过env(WritableEnvKey.DIRECTION, value)为作用域内组件设置局部布局方向。
从API版本26.0.0开始,新增env属性和键值WritableEnvKey.DIRECTION。
// xxx.ets
import { WithEnv } from '@kit.ArkUI';
@Entry
@Component
struct WithEnvExample2 {
@State directionValue: Direction = Direction.Ltr;
build() {
Column({ space: 12 }) {
Row({ space: 10 }) {
Column().backgroundColor('#F0FAFF').width(60).height('100%')
Column().backgroundColor('#2787D9').width(60).height('100%')
Column().backgroundColor('#004AAF').width(60).height('100%')
}.backgroundColor('#D5D5D5').width(200).height(50)
WithEnv() {
Row({ space: 10 }) {
Column().backgroundColor('#F0FAFF').width(60).height('100%')
Column().backgroundColor('#2787D9').width(60).height('100%')
Column().backgroundColor('#004AAF').width(60).height('100%')
}.backgroundColor('#D5D5D5').width(200).height(50)
}
.env(WritableEnvKey.DIRECTION, this.directionValue) // 设置局部布局方向
Button('change direction').onClick(() => {
if (this.directionValue === Direction.Ltr) {
this.directionValue = Direction.Rtl;
} else {
this.directionValue = Direction.Ltr;
}
})
}
.width('80%')
.height('30%')
}
} 