---
title: "useTheme"
description: "主题面板背后的状态与操作：主色、中性色、圆角、图标集、黑色主色与颜色模式，访客的选择保存在 localStorage，并能导出为 app.config 或 CSS 片段。自定义主题面板或在页面中切换主题时使用。"
canonical_url: "https://docs.mhaibaraai.cn/docs/reference/composables/use-theme"
---
# useTheme

> 主题面板背后的状态与操作：主色、中性色、圆角、图标集、黑色主色与颜色模式，访客的选择保存在 localStorage，并能导出为 app.config 或 CSS 片段。自定义主题面板或在页面中切换主题时使用。

`useTheme()` 驱动页头的 `ThemePicker`。站点在 `app.config` 中配置的主题是基准值，访客在面板里的修改覆盖基准值并持久化到 localStorage，key 以站点名（`site.name` 的 kebab-case）为前缀。

## 用法

```vue
<script setup lang="ts">
const { primary, neutral, mode, resetTheme } = useTheme()
</script>

<template>
  <UButton label="Blue" @click="primary = 'blue'" />
  <UButton label="Dark" @click="mode = 'dark'" />
  <UButton label="Reset" @click="resetTheme()" />
</template>
```

## 签名

```ts
function useTheme(): {
  primary: WritableComputedRef<string>
  primaryColors: string[]
  neutral: WritableComputedRef<string>
  neutralColors: string[]
  radius: WritableComputedRef<number>
  radiuses: number[]
  icon: WritableComputedRef<string>
  icons: { label: string, icon: string, value: string }[]
  mode: WritableComputedRef<string>
  modes: ComputedRef<{ label: string, icon: string }[]>
  blackAsPrimary: ComputedRef<boolean>
  setBlackAsPrimary: (value: boolean) => void
  color: ComputedRef<string | undefined>
  style: { innerHTML: ComputedRef<string>, id: string, tagPriority: number }[]
  hasCSSChanges: ComputedRef<boolean>
  hasConfigChanges: ComputedRef<boolean>
  configLabel: string
  exportCSS: () => string
  exportConfig: () => string
  resetTheme: () => void
}
```

## 返回值

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `primary` | `WritableComputedRef<string>` | 主色，写入 `appConfig.ui.colors.primary`；设置时会关闭黑色主色 |
| `primaryColors` | `string[]` | 可选主色：`vermilion` 加 Tailwind 调色板中的彩色 |
| `neutral` | `WritableComputedRef<string>` | 中性色，写入 `appConfig.ui.colors.neutral` |
| `neutralColors` | `string[]` | 可选中性色：`paper`、`slate`、`gray`、`zinc`、`neutral`、`stone`、`taupe`、`mauve`、`mist`、`olive` |
| `radius` | `WritableComputedRef<number>` | 圆角，单位 rem |
| `radiuses` | `number[]` | 可选圆角：`0`、`0.125`、`0.25`、`0.375`、`0.5` |
| `icon` | `WritableComputedRef<string>` | 图标集，写入时同步替换 `appConfig.ui.icons` |
| `icons` | `{ label, icon, value }[]` | 可选图标集：`lucide`、`phosphor`、`tabler` |
| `mode` | `WritableComputedRef<string>` | 颜色模式，写入 `colorMode.preference` |
| `modes` | `ComputedRef<{ label, icon }[]>` | `light`、`dark`、`system` 三项 |
| `blackAsPrimary` | `ComputedRef<boolean>` | 是否以黑色（暗色模式下为白色）作为主色 |
| `setBlackAsPrimary` | `(value: boolean) => void` | 切换黑色主色 |
| `color` | `ComputedRef<string \| undefined>` | 当前模式下中性色的 50 / 950 色值，用于 `theme-color` |
| `style` | `object[]` | 圆角与黑色主色对应的 `<style>` 标签，由外壳注入 head |
| `hasCSSChanges` | `ComputedRef<boolean>` | 圆角或黑色主色是否偏离基准值 |
| `hasConfigChanges` | `ComputedRef<boolean>` | 主色、中性色或图标集是否偏离基准值 |
| `configLabel` | `string` | 导出配置的文件名，固定为 `app.config.ts` |
| `exportCSS` | `() => string` | 导出与基准值不同的 CSS 变量 |
| `exportConfig` | `() => string` | 导出与基准值不同的 `defineAppConfig(...)` 代码 |
| `resetTheme` | `() => void` | 清除访客偏好，恢复 `app.config` 中的基准值 |

## 基准值

基准值在首次调用时从 `app.config` 读取：`ui.colors.primary`、`ui.colors.neutral`，以及 `theme.radius`（默认 `0.25`）、`theme.icons`（默认 `lucide`）、`theme.blackAsPrimary`（默认 `false`）。修改站点默认主题时改 `app.config`，不要在代码里写入这些 ref，详见 [主题与字体](https://docs.mhaibaraai.cn/docs/guide/theme)。

## 更新日志

See commit history for [layer/app/composables/useTheme.ts](https://github.com/mhaibaraai/movk-nuxt-docs/commits/main/layer/app/composables/useTheme.ts).

---

- [GitHub](https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/composables/useTheme.ts)


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
