ColorSchemeButton 使用手册

v1.0.2 · @snowui-design-system/components

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

在亮色与暗色主题之间切换，并以图标反馈当前方案，适合网站和应用的主题入口。

使用选择

用于切换浅色与深色方案。新代码使用此名称；ThemeButton 是兼容导出。设计风格切换使用 StyleButton。

通过 bind:scheme 或 onSchemeChange 同步明暗状态，defaultScheme 提供默认方案。
默认同步文档主题；局部控制设置 applyToDocument={false}。不提供 children 时使用纯图标布局。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { ColorSchemeButton } from '@snowui-design-system/components';</script> <ColorSchemeButton />

API

关键字	类型	默认值	描述
scheme	`ColorScheme`	—	当前配色方案，支持 bind:scheme。挂载时优先于 defaultScheme；点击更新该值，同步页面属性时也会跟随根节点变化。
defaultScheme	`ColorScheme`	—	挂载时的非受控初值；scheme 优先。均未提供时读取页面根节点；applyToDocument=false 时回退为 light。
applyToDocument	`boolean`	`true`	将当前状态同步到 document.documentElement：theme="dark"；亮色时移除 theme。false 时不读写或观察页面属性，由调用方处理主题目标；不写入 storage。
ariaLabel	`string`	—	覆盖按钮的可访问名称；默认描述点击后切换到的状态，跟随 LocaleProvider。
lightIcon	`Snippet`	`—（内置图形）`	替换当前为 light 时显示的 Sun 图标。仅改变图形，不接管切换逻辑。
darkIcon	`Snippet`	`—（内置图形）`	替换当前为 dark 时显示的 Moon 图标。仅改变图形，不接管切换逻辑。
children	`Snippet`	—	显示在状态图形之后的自定义内容；未提供时宿主 Button 自动使用 iconOnly 布局。
disabled	`boolean`	`false`	禁用按钮操作；不会阻止外部绑定值或页面属性的同步。
onSchemeChange	`(scheme: ColorScheme) => void`	—	用户点击切换后接收新值；初始化、外部赋值及页面属性观察同步不会调用此回调。
onclick	`(event: MouseEvent) => void`	—	有效点击时先调用，再执行状态切换；当前实现不会以 preventDefault() 取消后续切换。disabled 时不调用。

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

使用

<script lang="ts">  import { ColorSchemeButton } from "@snowui-design-system/components";</script> <ColorSchemeButton bare />

ColorSchemeButton 平铺 Button 的兼容 Props，支持全部变体与尺寸。默认读取 document.documentElement：theme="dark" 为暗色，移除该属性为亮色。无额外 children 时，组件主动向 Button 声明 iconOnly=true；内置 Sun / Moon 图标跟随 Button 尺寸上下文：普通 icon-only 的 sm / md / lg 为 16 / 20 / 24px，bare icon-only 则沿用 Button 的 12 / 16 / 20px。

旧名称 ThemeButton 仅作为弃用兼容别名保留；新代码统一使用 ColorSchemeButton。

点击后立即更新方案，不写入 storage；图标替换使用 150ms 动效，不对整页主题增加过渡。applyToDocument={false} 时组件只维护受控状态，适合由 Test、iframe 等宿主管理实际主题目标。

此区域的内容受保护。AI 在修改此区域前必须请求用户审查。

ColorSchemeButton 样式覆盖

先阅读完整 LICENSE；同任务、同版本、同范围去重。

优先用组件公开 Props 匹配合适样式，尽可能保留原有视觉。确需改写时按样式选择与改写顺序使用自己的 class（含项目已有 Tailwind）或实例 style。以下名称来自源码实际消费的公开 override；先核对目标作用域，不修改私有 DOM。采用 SnowUI Token 时选择正确类别，外部应用不被要求安装一方 utilities。

变量	用途与默认参考
`--snowui-color-scheme-button-motion-duration-override`	default: 150ms; Button hover / click

设计指南 · Token · 组合边界

ColorSchemeButton 类型与状态

必填属性：无具名必填属性。

可双向绑定：bind:scheme。

继承声明：Omit< ButtonProps, "children" | "onclick" | "disabled" | "aria-pressed" >。继承能力以基类公开文档为准；Omit 中的字段已排除，不能按基类原样使用。

共享 Frame API · 返回 API

以下为公开属性实际引用的类型声明，来自源码；Svelte Snippet 表示内容片段，ComponentProps 表示对应组件的 Props。

ColorScheme

来源：components/src/components/ColorSchemeButton.svelte

export type ColorScheme = "light" | "dark";

ButtonProps

来源：components/src/components/ColorSchemeButton.svelte

type ButtonProps = ComponentProps<typeof Button>;