深色模式 - PythonIDE Docs

在 appui 中，外观由 系统语义色字符串、环境色方案 与 材质背景 共同决定。优先使用语义色和材质，让页面自动适配浅色、深色和高对比度环境。

#预期效果

示例会展示语义色、材质背景、强制色彩方案和符号配色在浅色/深色下的表现。

#系统语义色（随浅色/深色变化）

在 foreground_color、background(color=...)、fill、stroke 等接受颜色的位置，可直接传入下列字符串（不区分大小写；部分名称支持 snake_case 别名，如 secondary_label）。

背景与分组

systemBackground（别名：system_background、background）
secondarySystemBackground（secondary_system_background、secondary_background）
tertiarySystemBackground（tertiary_system_background、tertiary_background）
systemGroupedBackground、secondarySystemGroupedBackground、tertiarySystemGroupedBackground

标签与分隔

label、secondaryLabel、tertiaryLabel、quaternaryLabel
separator、opaqueSeparator
placeholderText（placeholder_text、placeholder）

填充层级

systemFill（system_fill、fill）
secondarySystemFill、tertiarySystemFill、quaternarySystemFill

系统调色板

systemBlue、systemRed、systemGreen、systemOrange、systemPurple
systemPink、systemYellow、systemTeal、systemCyan、systemIndigo
systemGray、systemBrown、systemMint

python

import appui

state = appui.State()

def body():
    return (appui.VStack([
        appui.Text("主标签色").foreground_color("label"),
        appui.Text("次要说明").foreground_color("secondaryLabel"),
        appui.Divider(),
        appui.Text("强调链接").foreground_color("systemBlue"),
    ], spacing=12)
    .padding()
    .frame(max_width=400)
    .background(color="systemGroupedBackground", corner_radius=12))

appui.run(body, state=state, presentation="sheet")

#preferred_color_scheme：强制浅色或深色

对子树应用 .preferred_color_scheme(scheme)，scheme 为 'light' 或 'dark'。

python

import appui

state = appui.State(force="dark")


def set_light():
    state.force = "light"


def body():
    return (appui.VStack([
        appui.Text("强制深色环境下的卡片").foreground_color("label"),
        appui.Button("切换为浅色预览", action=set_light),
    ], spacing=16)
    .padding()
    .background(color="secondarySystemBackground", corner_radius=16)
    .preferred_color_scheme(state.force))

appui.run(body, state=state, presentation="sheet")

#材质背景：background(material=...)

使用 模糊材质 时，不要同时传 color。material 常用取值如下：

`material` 参数值	说明
`ultra_thin` 或 `ultra_thin_material`	`ultraThinMaterial`
`thin` 或 `thin_material`	`thinMaterial`
`regularMaterial`、`regular` 或 `regular_material`	`regularMaterial`
`thick` 或 `thick_material`	`thickMaterial`
`ultra_thick` 或 `ultra_thick_material`	`ultraThickMaterial`

python

import appui

state = appui.State()

def body():
    return (appui.VStack([
        appui.Text("玻璃质感背景").foreground_color("label"),
        appui.Text("副标题").font("caption").foreground_color("secondaryLabel"),
    ], spacing=8)
    .padding(20)
    .background(material="regularMaterial", corner_radius=14))

appui.run(body, state=state, presentation="sheet")

background 还可配合 gradient、opacity、corner_radius 等参数；详见 View.background 的 appui.py 文档字符串。

#实践建议

优先语义色：卡片与列表用 secondarySystemGroupedBackground、label 等，减少硬编码 #RRGGBB。
对比度：在 preferred_color_scheme('dark') 下仍用 label / secondaryLabel 分层，而不是纯灰。
材质与圆角：background(material='regular', corner_radius=12) 在圆角矩形内裁剪材质，视觉更统一。
调试：用 preferred_color_scheme 固定一种方案，截图对比浅色与深色下的 systemFill 层级是否清晰。

python

import appui

# 仅构建视图树，验证修饰符链可序列化。
def body():
    return appui.Text("Hi").padding().background(material="thin", corner_radius=8)

tree = body()
assert tree is not None

#与 SF Symbols 搭配

导航与媒体类符号在深浅背景下都清晰，例如 chevron.left、play.fill、gearshape.fill。配合 Image(system_name=...) 与 symbol_rendering_mode('hierarchical') 可得到分层着色效果。

python

import appui

state = appui.State()

def body():
    return appui.HStack([
        appui.Image(system_name="sun.max.fill").foreground_color("systemYellow"),
        appui.Image(system_name="moon.fill").foreground_color("systemIndigo"),
    ], spacing=24).padding()

appui.run(body, state=state, presentation="sheet")

更多媒体与符号用法见 appui-guide-media.md。