---
url: /components/theme-toggle.md
---
# ThemeToggle 主题切换

`EvThemeToggle` 是明暗主题切换按钮，内部基于 `useTheme`：点击切换 `html.dark` 类驱动全库令牌重映射，
日/月图标随状态变化。主题偏好写入 localStorage（key `ev-theme`），首次访问跟随系统。

## 基础用法

```vue
<EvNavbar logo-text="cumubase" :items="navItems">
  <template #actions>
    <EvThemeToggle />
  </template>
</EvNavbar>
```

::: info 底层 API
需要自定义切换逻辑时直接使用组合式 API：

```js
import { useTheme } from '@wil-works/evoke-ui'
const { isDark, toggleTheme, setTheme } = useTheme()
setTheme(true)  // 显式切暗色
```

:::

## API

### Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| variant | 按钮变体（同 EvIconButton） | `'ghost' \| 'soft' \| 'outline' \| 'primary' \| 'dark'` | `'ghost'` |
| size | 尺寸 | `'small' \| 'default' \| 'large'` | `'default'` |
| round | 正圆形态 | boolean | `false` |