> AI coding agents: see [/llms.txt](/llms.txt) for the full documentation index. Markdown version: [/docs/manual/zh/concepts/theme.md](/docs/manual/zh/concepts/theme.md).

---
title: 主题
description: 借助 Nuxt UI 灵活的主题系统，自定义 TockDocs 文档的外观。
navigation:
  icon: i-lucide-paint-roller
---

TockDocs 基于 Nuxt UI 构建，充分利用 Tailwind CSS v4、CSS 变量。Tailwind Variants API 提供了灵活且可扩展的主题系统。

::tip{to="https://ui.nuxt.com/getting-started/theme"}
有关 Nuxt UI 主题的完整概述，请查看 Nuxt UI 文档。
::

## 使用 `@theme` 覆盖

您可以在 `@theme` 指令中使用 CSS 变量来自定义主题，定义项目的自定义设计令牌，如字体、颜色和断点。

您可以通过在应用中创建 `main.css` 文件来覆盖此主题：

::code-group
```css [assets/css/main.css]
@import 'tailwindcss';
@import '@nuxt/ui';

@theme {
  --font-sans: 'Public Sans', sans-serif;

  --breakpoint-3xl: 1920px;

  --color-green-50: #effdf5;
  --color-green-100: #d9fbe8;
  --color-green-200: #b3f5d1;
  --color-green-300: #75edae;
  --color-green-400: #00dc82;
  --color-green-500: #00c16a;
  --color-green-600: #00a155;
  --color-green-700: #007f45;
  --color-green-800: #016538;
  --color-green-900: #0a5331;
  --color-green-950: #052e16;
}
```

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
})
```
::

## 颜色

TockDocs 使用预配置的颜色别名来为组件添加样式并驱动整个 UI 中的 `color` 属性。

每个标签代表一个默认别名：

- :u-badge{label="primary" variant="outline"} → 主要品牌颜色，用作组件的默认颜色 :br [(默认: green)]{.text-xs,text-muted}
- :u-badge{color="secondary" label="secondary" variant="outline"} → 辅助颜色，补充主要颜色 :br [(默认: blue)]{.text-xs,text-muted}
- :u-badge{color="success" label="success" variant="outline"} → 用于成功状态 :br [(默认: green)]{.text-xs,text-muted}
- :u-badge{color="info" label="info" variant="outline"} → 用于信息状态 :br [(默认: blue)]{.text-xs,text-muted}
- :u-badge{color="warning" label="warning" variant="outline"} → 用于警告状态 :br [(默认: yellow)]{.text-xs,text-muted}
- :u-badge{color="error" label="error" variant="outline"} → 用于表单错误验证状态 :br [(默认: red)]{.text-xs,text-muted}
- :u-badge{color="neutral" label="neutral" variant="outline"} → 用于背景、文本等的中性颜色 :br [(默认: slate)]{.text-xs,text-muted}

您可以通过更新 `app.config.ts` 文件中的 `ui.colors` 键来全局自定义这些颜色：

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    colors: {
      primary: 'blue',
      neutral: 'zinc',
    },
  },
})
```

## 组件

除了颜色之外，所有 [Nuxt UI 组件](https://ui.nuxt.com/components) 都可以通过 `app.config.ts` 全局设置主题。

您可以通过使用与组件内部主题对象相同的结构来覆盖任何组件的外观（显示在[每个组件页面的末尾](https://ui.nuxt.com/components/card#theme)）。

例如，更改所有按钮的字体粗细：

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    button: {
      slots: {
        base: 'font-bold',
      },
    },
  },
})
```

在此示例中，`font-bold` 类将覆盖所有按钮上默认的 `font-medium` 类。

::note{to="https://ui.nuxt.com/components/button#theme"}
要探索每个组件的可用主题选项，请参阅其对应 Nuxt UI 文档页面中的 **Theme** 部分。
::

## TockDocs 子组件

TockDocs 内部使用多个 Nuxt UI 组件用于导航、目录和子导航。您可以通过 `app.config.ts` 使用 `defaultVariants` 键自定义它们的默认变体。

以下组件可配置：

| 组件                                                                     | 键                      | 默认值                                  |
| ---------------------------------------------------------------------- | ---------------------- | ------------------------------------ |
| [ContentToc](https://ui.nuxt.com/components/content-toc)               | `ui.contentToc`        | `highlight: true`                    |
| [ContentNavigation](https://ui.nuxt.com/components/content-navigation) | `ui.contentNavigation` | `variant: 'link'`, `highlight: true` |
| [NavigationMenu](https://ui.nuxt.com/components/navigation-menu)       | `ui.navigationMenu`    | `variant: 'pill'`, `highlight: true` |

例如，要将目录高亮样式更改为 `circuit` 并将侧边栏导航变体切换为 `pill`：

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    contentToc: {
      defaultVariants: {
        highlightVariant: 'circuit',
        highlightColor: 'secondary',
      },
    },
    contentNavigation: {
      defaultVariants: {
        variant: 'pill',
        highlight: false,
      },
    },
  },
})
```

每个组件支持以下变体选项：

- **`highlight`** — 显示活动指示线（`true` 或 `false`）
- **`highlightColor`** — 指示器的颜色（`primary`、`secondary`、`neutral` 等）
- **`variant`** — 视觉样式（`pill` 或 `link`，如适用）
- **`highlightVariant`** — 指示器样式（`straight` 或 `circuit`，仅 ContentToc）
- **`color`** — 活动链接的基础颜色