附录: 颜色参考 - PythonIDE Docs

appui 支持系统语义色、十六进制颜色、RGB 元组和灰度值。理解这些规则有助于在 Text、Shape、Chart 与修饰符中一致地配色。

#支持的写法

形式	示例	说明
命名字符串	`"systemBlue"`、`"label"`	与 iOS 语义色、系统色名称一致（由系统解析）。
十六进制	`"#FF5533"`、`"#22AAFFAA"`	支持 `#RRGGBB` 或带透明度的 8 位形式。
RGB / RGBA 元组	`(1.0, 0.2, 0.0)`、`(0, 0.5, 1, 0.4)`	分量范围为 0.0–1.0，转换为 `#RRGGBB` / `#RRGGBBAA`。
灰度标量	`0.35`	数值会转换为对应灰度颜色。
`Color` 视图	`appui.Color(value="systemTeal")`	用于在布局中放置一块纯色区域；亦可用 `red` / `green` / `blue` 分量构造。

#语义色与背景层次

下列名称常用于阅读层次与背景分层（浅色模式下对比更明显；深色模式下系统会自动调整对比度）：

文字层次：label、secondaryLabel、tertiaryLabel
背景层次：systemBackground、secondarySystemBackground、tertiarySystemBackground
分隔与填充：separator、systemFill、secondarySystemFill、tertiarySystemFill（若当前 SDK 映射存在）

#系统强调色（摘录）

适合图表、图标与强调文案：systemBlue、systemRed、systemGreen、systemOrange、systemPurple、systemPink、systemYellow、systemTeal、systemCyan、systemIndigo、systemGray、systemBrown、systemMint

#深浅色对比的实践建议

正文与背景：正文优先 label 配 systemBackground，次级说明用 secondaryLabel，避免硬编码纯黑纯白。
卡片与列表：卡片背景用 secondarySystemBackground 或 tertiarySystemBackground，分隔用 separator 或细线 Divider()。
强调操作：主按钮 tint 与关键数字可用 systemBlue 或品牌主色十六进制；警告用 systemOrange / systemRed。
强制预览：调试深浅色时，可在根视图上链式调用 .preferred_color_scheme('light') 或 .preferred_color_scheme('dark')（参见下方示例）。

#可运行示例：色板与深浅切换

python

import appui

state = appui.State(
    preview_dark=True,
    accent_hex="#5AC8FA",
)


def swatch_row(title, color_token):
    return appui.HStack(
        [
            appui.Text(title).frame(max_width=appui.infinity, alignment="leading"),
            appui.Rectangle()
            .fill(color_token)
            .frame(width=52, height=30)
            .corner_radius(6)
            .overlay(appui.Rectangle().stroke("separator", line_width=1).corner_radius(6)),
        ],
        spacing=12,
    )


def set_preview_dark(value):
    state.preview_dark = bool(value)


def set_accent_hex(value):
    state.accent_hex = value


def body():
    scheme = "dark" if state.preview_dark else "light"
    palette = appui.Form(
        [
            appui.Section(
                content=[
                    appui.Toggle(
                        "深色预览",
                        is_on=state.preview_dark,
                        on_change=set_preview_dark,
                    ),
                    appui.LabeledContent(
                        "自定义强调色",
                        content=appui.ColorPicker(
                            label="",
                            selection=state.accent_hex,
                            on_change=set_accent_hex,
                        ),
                    ),
                ],
                header="外观",
            ),
            appui.Section(
                content=[
                    swatch_row("label", "label"),
                    swatch_row("secondaryLabel", "secondaryLabel"),
                    swatch_row("systemBackground", "systemBackground"),
                    swatch_row("secondarySystemBackground", "secondarySystemBackground"),
                ],
                header="语义色",
            ),
            appui.Section(
                content=[
                    swatch_row("systemBlue", "systemBlue"),
                    swatch_row("systemGreen", "systemGreen"),
                    swatch_row("systemOrange", "systemOrange"),
                    swatch_row("RGB 元组红", (0.95, 0.2, 0.25)),
                    swatch_row("十六进制", state.accent_hex),
                ],
                header="强调与自定义",
            ),
        ]
    ).navigation_title("颜色参考")
    return appui.NavigationStack(palette).preferred_color_scheme(scheme)


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

#与 `Shape` / `Chart` 的配合

Rectangle().fill("systemIndigo") 与 RoundedRectangle(corner_radius=8).fill((0.2, 0.6, 0.9)) 都支持同样的颜色表达。
Chart(..., color="systemTeal") 的 color 参数同样支持上述写法。

#常见误区

混用 0–255 与 0–1：元组形式为 0–1 浮点；若手边是 8 位 RGB，请先除以 255 或改用 #RRGGBB 字符串。
过度使用纯语义灰：图表多系列时，仍建议为每条序列指定可区分的系统色或十六进制色。

#浅色与深色下的观感差异（概念说明）

语义色并非固定 RGB，而是随 traitCollection 与界面层级自动映射：

在浅色模式下，systemBackground 趋向明亮底，label 趋向近黑文本，层次靠 secondaryLabel 等拉开。
在深色模式下，同一 token 会切换为更高对比、更低眩光的组合，避免大块刺眼的纯白。
调试时可用上文示例中的 .preferred_color_scheme('light' | 'dark') 固定外观；发布给用户时通常移除该修饰符以尊重系统设置。

#与 `foreground_color` / `foreground_style` / `tint` 的分工

foreground_color：多用于 Text、Image 等着色前景内容。
foreground_style：可承载更复杂的前景色描述，如渐变名或材质名。
tint：作用于控件强调色（如按钮、开关），与 Button(...).button_style("bordered_prominent") 等组合时影响默认着色。

#可运行片段：纯色条与十六进制

下面是一段不依赖 NavigationStack 的极简布局，用于快速验证十六进制、元组和语义色是否能正常渲染。

python

import appui

state = appui.State()


def body():
    return appui.VStack(
        [
            appui.Text("Hex 与元组").font("headline"),
            appui.HStack(
                [
                    appui.Rectangle().fill("#34C759").frame(width=60, height=32).corner_radius(6),
                    (
                        appui.Rectangle()
                        .fill((0.95, 0.45, 0.1))
                        .frame(width=60, height=32)
                        .corner_radius(6)
                    ),
                    (
                        appui.Rectangle()
                        .fill("systemIndigo")
                        .frame(width=60, height=32)
                        .corner_radius(6)
                    ),
                ],
                spacing=12,
            ),
        ],
        spacing=16,
    ).padding(24)


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

#语义色与系统色速查表（字符串字面量）

下列名称均可直接传给 foreground_color、background(color=...)、tint、Chart(..., color=...) 等接受颜色值的 API。

文本与灰阶

label, secondaryLabel, tertiaryLabel

背景层次

systemBackground, secondarySystemBackground, tertiarySystemBackground

分隔与填充

separator, systemFill, secondarySystemFill, tertiarySystemFill

系统强调色（摘录）

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

在深浅色之间切换时，上述 token 的相对对比度由系统维护；自定义十六进制色不会自动随模式反转，需要自行准备两套色值或在运行时根据 preferred_color_scheme 切换。

#设计检查清单

主要正文是否使用 label 而非硬编码 "black" / "white"。
卡片背景是否比页面背景高一级（secondarySystemBackground 对比 systemBackground）。
图表是否为每条序列选择可区分的系统色或品牌色，并避免红绿色盲仅靠红/绿区分关键状态。
是否在调试完成后移除强制的 .preferred_color_scheme，以尊重用户系统设置。