主题主色选择

概述

SThemePrimarySelect 是一个绑定到当前 SConfigProvider 主题的上下文下拉选择。它列出全部 26 个内置调色板（PaletteKey），并把选中的一项写回主题 primary，因此所有由品牌色派生的 token 会一次性更新。

适用于需要「一键换品牌色」的场景 —— 设置面板、顶栏配色菜单，或作为 SThemeCustomizer 的精简替代。当用户还需要基础色板、圆角、字号、间距或自定义预设时，请改用 SThemeCustomizer。

它与 SThemeModeSelect、SThemeModeSwitch 共享同一主题上下文：三者读写同一份 provider 状态，无需额外 props 即可保持同步。

用法

特性

• 🎨 全部 26 个内置调色板作为选项，直接取自主题引擎的 PALETTE_KEYS
• 🧩 simple 模式把色板堆叠收敛成单个 500 色块，触发器与每个选项都生效
• 🎚 size 透传给底层 select 触发器，与主题尺寸刻度（xs…2xl）一致
• 🔗 通过共享主题上下文写入 —— 没有 modelValue，也没有本地镜像状态
• ♿ 触发器带 aria-label，没有可见文案时依然可被辅助技术识别
• 🎯 与 SThemeBaseSelect 复用同一 ColorDecorator 色块渲染器，两处渲染完全一致

演示

API

注意事项

架构与对标差异

• 该组件是 UI 层 组件（@vean/ui）：它组合已有的 SSelect 与共享的 ColorDecorator，因此 @vean/aria 中没有对应实现。
• simple 默认为 true，因为精简形态正是本组件的目的。传 simple="false" 可获得与主题定制器相同的五级堆叠。

提醒

• 必须渲染在 SConfigProvider 内部，否则 useTheme 会抛出异常。
• 它不接受 modelValue。若要用自己的 store 驱动主色，请使用主题上下文（useTheme().primary），或给 provider 传 theme / themeConfig。
• simple="false" 使用定制器默认的层级堆叠 [100, 900, 300, 800, 600]，它刻意不是由浅到深的色阶 —— 那是「品牌识别」取样，而不是刻度。

常见问题

为什么没有 modelValue？

主色属于主题 provider，而不是这个组件。在组件内部再绑一份会制造第二个真相来源，与生成的 CSS token 漂移。需要读取当前值时用 useTheme().primary。

如何只显示色点、不显示色板名称？

这正是 simple 的作用 —— 把色板堆叠收敛为单个 500 色块。选项文案仍来自底层 select；如果需要纯图标触发器，可通过 SSelect 的 ui 槽位覆盖隐藏文案。

可以限制可选色板范围吗？

目前没有对应 props，列表来自主题引擎的 PALETTE_KEYS。若需要子集，请直接用过滤后的 items 组合 SSelect。

为什么色块颜色和我设置的 CSS 变量不一致？

色块通过 paletteColor(key, level, 'hsl') 从调色板定义解析，而不是读取计算后的 CSS。主题上的 overrides 会改变渲染出的 token，但不会改变调色板取样。