环境值 API
environment_value、color_scheme、locale、layout_direction 和动态字体。
environment_value(key, value) 用来设置少量通用环境值。它是一个通用入口；如果已经有更直接的专用修饰符，优先用专用修饰符。
#签名
已复制
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)#专用修饰符优先
这些场景优先用专用 API，不要为了“统一写法”强行全部塞进 environment_value：
- 明暗模式：
preferred_color_scheme("dark") - 多行文本对齐：
multiline_text_alignment("leading") - 截断：
truncation_mode("middle") - 输入框自动纠错：
TextField(..., autocorrection_disabled=...)
#注意事项
environment_value更适合“给一整段视图树施加环境”，不是每个修饰符都拿它代替。dynamic_type_size依赖较新的系统版本；过低系统可能不会生效。autocorrection的实际体验最稳的方式仍然是直接在输入控件构造参数里声明。- 不在当前支持表里的 key 不保证生效。