环境值 API
environment_value、color_scheme、locale、layout_direction 和动态字体。
environment_value(key, value) 用来设置少量通用环境值。它是一个通用入口；如果已经有更直接的专用修饰符，优先用专用修饰符。
读取系统环境使用 EnvironmentReader。写入和读取是两个方向：environment_value 向子树提供值，EnvironmentReader 把设备当前值写回 Python State。
#签名
已复制
environment_value(key, value)#什么时候用
- 你想批量给一段视图树施加语言、方向、动态字体或文本环境。
- 你要覆盖
locale、layout_direction、dynamic_type_size这类没有独立高频包装的环境项。 - 你已经知道目标 key，不想拆成多个专用修饰符。
#当前支持的 key
| key | 值 | 作用 | 更直接的写法 |
|---|---|---|---|
color_scheme | light / dark | 强制明暗模式。 | preferred_color_scheme(...) |
layout_direction | left_to_right / right_to_left | 控制布局方向。 | 无 |
locale | 语言地区标识，如 zh_CN、en_US | 影响日期、数字、本地化格式。 | 无 |
line_spacing | 数字，如 4、6 | 设置行距。 | 无 |
multiline_text_alignment | leading / center / trailing | 多行文本对齐。 | multiline_text_alignment(...) |
allow_tight_spacing | True / False | 是否允许文字收紧间距。 | 无 |
truncation_mode | tail / head / middle | 文本截断位置。 | truncation_mode(...) |
dynamic_type_size | xSmall、small、medium、large、xLarge、xxLarge、xxxLarge、accessibility1 到 accessibility5 | 动态字体等级。 | 无 |
redaction | placeholder / none | 占位式骨架屏或取消 redaction。 | 无 |
autocorrection | True / False | 控制自动纠错；对输入控件更有意义。 | 对 TextField / SecureField 优先用构造参数 |
text_case | uppercase / lowercase / none | 统一大小写风格。 | 无 |
#推荐写法
已复制
import appui
def body():
return appui.NavigationStack(
appui.VStack([
appui.Text("环境值示例"),
appui.Text("这段文字会使用更大的动态字体和更宽的行距。")
.line_limit(2),
], spacing=12)
.padding()
.navigation_title("Environment")
.environment_value("locale", "zh_CN")
.environment_value("dynamic_type_size", "xLarge")
.environment_value("line_spacing", 6)
)
appui.run(body)#EnvironmentReader
已复制
EnvironmentReader(content=None, values=None, on_change=None, keys=None,
onChange=None, children=None)EnvironmentReader 是透明容器，不改变布局。values 推荐传 State.bind.<field>；系统环境真正变化时才会回写，不需要 Timer 或轮询。
可读 key：color_scheme、color_scheme_contrast、display_scale、dynamic_type_size、horizontal_size_class、vertical_size_class、layout_direction、locale、legibility_weight、reduce_motion、reduce_transparency、differentiate_without_color、scene_phase。
已复制
import appui
state = appui.State(environment={})
def body():
values = state.environment
summary = (
f"{values.get('horizontal_size_class', 'unknown')} · "
f"{values.get('color_scheme', 'unknown')}"
)
content = appui.VStack([
appui.Text("Responsive layout").font("headline"),
appui.Text(summary).foreground_color("secondaryLabel"),
], spacing=8).padding()
return appui.EnvironmentReader(
content,
values=state.bind.environment,
keys=[
"horizontal_size_class",
"color_scheme",
"reduce_motion",
"dynamic_type_size",
],
)
appui.run(body, state=state)#专用修饰符优先
这些场景优先用专用 API，不要为了“统一写法”强行全部塞进 environment_value：
- 明暗模式：
preferred_color_scheme("dark") - 多行文本对齐：
multiline_text_alignment("leading") - 截断：
truncation_mode("middle") - 输入框自动纠错：
TextField(..., autocorrection_disabled=...)
#注意事项
environment_value更适合“给一整段视图树施加环境”，不是每个修饰符都拿它代替。EnvironmentReader只接受上表列出的 key；未知 key 会在 Python 构建期直接报错，不会静默忽略。reduce_motion=True时，优先使用Animation(...).respecting_reduce_motion()和Transition(...).respecting_reduce_motion()。dynamic_type_size依赖较新的系统版本；过低系统可能不会生效。autocorrection的实际体验最稳的方式仍然是直接在输入控件构造参数里声明。- 不在当前支持表里的 key 不保证生效。