主题切换
在亮色、暗色与跟随系统之间切换主题的组件。
pnpm dlx shadcn add @chaos-design/theme-switchnpx shadcn@latest add @chaos-design/theme-switchyarn dlx shadcn add @chaos-design/theme-switchbunx shadcn add @chaos-design/theme-switch全部配置
下面把 ThemeSwitch 的每个属性都摆出来:左键点击任意开关的下拉菜单,或直接点受控卡片上的按钮。
需要注意的三点:
- 多个开关默认联动。 非受控开关之间通过模块级广播实时同步,所以在这个页面里切换一次主题,八个开关会一起变。
- 受控开关不写存储。 传入
value后组件仍然会把主题应用到文档,但不再写入localStorage、也不再同步其他开关。 attribute会作用于整个文档。 设为data-theme时组件会写入data-theme属性并移除.dark类,因此你的 CSS 需要按[data-theme="dark"]来匹配:
<ThemeSwitch attribute="data-theme" />[data-theme="dark"] {
/* 你的暗色变量 */
}安装
npm install @chaos-design/theme-switch使用方式
import { ThemeSwitch } from '@chaos-design/theme-switch';
export default function Demo() {
return <ThemeSwitch />;
}配合无闪烁脚本(放在服务端渲染的页面 <head> 中),在首次绘制之前完成主题应用:
import { ThemeScript } from '@chaos-design/theme-switch';
export default function Root() {
return (
<html lang="zh" suppressHydrationWarning>
<head>
<ThemeScript />
</head>
<body>{/* ... */}</body>
</html>
);
}Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| value | Theme | - | 受控主题值('light' | 'dark' | 'system')。 |
| defaultTheme | Theme | 'system' | 未存储时的初始主题。 |
| onValueChange | (theme: Theme) => void | - | 用户切换主题时的回调。 |
| storageKey | string | 'theme' | 持久化主题的 localStorage 键名。 |
| enableSystem | boolean | true | 是否提供“跟随系统”选项。 |
| attribute | 'class' | 'data-theme' | 'class' | 主题写入文档根节点的方式。 |
| disableTransitionOnChange | boolean | true | 切换主题时禁用 CSS 过渡,避免页面闪现。 |
| labels | Partial<Record<Theme, string>> | - | 自定义各项的文本(国际化)。 |
| icons | Partial<Record<Theme, ComponentType>> | - | 自定义各项的图标。 |
| triggerLabel | string | - | 触发按钮的 aria-label。 |
| className | string | - | 自定义触发按钮类名。 |
| classNames | ThemeSwitchClassNames | - | 内部元素自定义类名。 |
ThemeSwitchClassNames
| 属性 | 说明 |
|---|---|
| trigger | 触发按钮。 |
| content | 弹出菜单。 |
| item | 菜单项。 |
| icon | 图标。 |