ColorModeSwitcher 颜色模式切换
新粗野主义风格的颜色模式切换组件，基于 useTheme() 组合式函数，提供三种显示模式。
预览
图标模式（默认）
按钮模式
选择模式
不包含系统选项
安装
pnpm dlx brutx-vue@latest add color-mode-switcher用法
图标模式（默认）
点击图标在 light / dark / system 之间循环切换。
<script setup>
import { ColorModeSwitcher } from 'brutx-ui-vue'
</script>
<template>
<ColorModeSwitcher />
</template>按钮模式
显示图标和文字标签的组合按钮，点击循环切换。
<template>
<ColorModeSwitcher display="button" />
</template>下拉选择模式
基于 Select 组件的下拉选择器，可直接选择目标模式。
<template>
<ColorModeSwitcher display="select" />
</template>隐藏 system 选项
通过 showSystem 属性控制是否显示 "system" 选项。当设为 false 时，循环切换将仅在 light / dark 之间进行。
<template>
<ColorModeSwitcher :show-system="false" />
</template>边界行为： 若当前模式恰为被隐藏的
system（如未持久化偏好且系统为暗色时useTheme默认置为 system），图标/按钮点击会保持现状而不跳转；下拉选择模式的展示值回退为实际解析出的亮暗模式（resolvedColorMode），与页面实际主题一致，避免「页面暗色而下拉框显示 light」的感知偏差；程序化传入system不再被接受。
变体
| 变体 | 说明 |
|---|---|
icon | 图标模式，仅显示当前模式对应的图标 |
button | 按钮模式，显示图标和文字标签的组合按钮 |
select | 下拉选择模式，基于 Select 组件的下拉选择器 |
组合式函数
ColorModeSwitcher 内部使用 useTheme() 组合式函数获取当前颜色模式并切换。生产应用推荐在上层通过 provideTheme() 提供主题上下文；内置共享单例仅作为兼容兜底。测试、多应用同页或热更新场景可调用 destroyBrutxFallbacks() 集中清理 theme/toast/message 的 fallback 状态。
颜色模式会持久化到 localStorage（键名 brutx-color-mode）。当选择 system 时，将跟随系统偏好设置，并监听 prefers-color-scheme 媒体查询的变化。
API 参考
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
display | "button" | "icon" | "select" | undefined | "icon" | 选择图标按钮、带当前模式文本的按钮或下拉选择器；两种按钮模式按可用模式顺序循环切换。 |
详情声明类型"button" | "icon" | "select" | undefined 字面量
默认值详情
来源packages/ui/src/components/color-mode-switcher/ColorModeSwitcher.vue | |||
showSystem | boolean | undefined | true | 将跟随系统模式包含在循环切换与下拉选项中。
|
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/color-mode-switcher/ColorModeSwitcher.vue | |||
class | string | undefined | undefined | 传给当前展示模式的根组件：按钮模式为 Button，下拉模式为 SelectRoot。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/color-mode-switcher/ColorModeSwitcher.vue | |||
可访问性
- 键盘操作：支持
Enter/Space触发切换 - ARIA 属性：图标按钮包含当前模式的文本描述