> Leaf UI 0.6.0 · Package: @ifhover/leaf-ui · Source: b30c3d3a8fa9c5e15d0d0522cebfbd33f60c6b06
> Browser documentation: https://ifhover.github.io/leaf-ui/v/0.6.0/guide/theming.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms-full.txt.

# 定制主题

颜色、圆角和深色模式都通过 ConfigProvider 的 `theme` 设置。通常几行配置就够了，其他样式会自动跟随。

## 改颜色和圆角

在应用入口用 ConfigProvider 包住页面。下面把主题色改成紫色，基础圆角改成 8px：


保存更改

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/theming/basic.tsx"
import { Button, ConfigProvider } from '@ifhover/leaf-ui';

export function ThemeBasic() {
  return (
    <ConfigProvider theme={{ primaryColor: '#7654c6', borderRadius: 8 }}>
      <Button>保存更改</Button>
    </ConfigProvider>
  );
}
```

展开代码

把示例中的 Button 换成你的应用内容即可。按钮、输入框、选择器及浮层会一起使用这份主题；悬停、按下和焦点颜色会自动生成。

`borderRadius` 是圆角的基准值。卡片、弹窗等会按各自的层级生成圆角，因此不必逐个组件设置。数字表示像素，也支持 `'0.5rem'` 等 CSS 长度。

### 常用参数

下面这些参数都放在 `theme` 中，只写需要修改的项。

| 参数              | 常见写法                  | 用途                     |
| --------------- | --------------------- | ---------------------- |
| `primaryColor`  | `'#7654c6'`           | 设置主题色，相关交互颜色自动生成。      |
| `borderRadius`  | `8`                   | 调整基础圆角，`0` 为直角。        |
| `appearance`    | `'light'` / `'dark'`  | 设置浅色或深色外观。             |
| `controlHeight` | `40`                  | 调整单行控件的基础高度，小、大尺寸同步变化。 |
| `fontSize`      | `14`                  | 设置组件基础字号。              |
| `fontFamily`    | `'Inter, sans-serif'` | 设置字体；字体文件由应用加载。        |
| `motion`        | `false`               | 关闭当前区域的动效，保留正常操作。      |

未设置的字段继承外层配置。默认使用浅色外观、10px 基础圆角、36px 基础控件高度和 14px 字号。

完整参数见 [LeafTheme](https://ifhover.github.io/leaf-ui/v/0.6.0/components/config-provider.md#leaftheme)。需要单独调整文字色、背景色或某个尺寸时，再查阅 [LeafThemeTokens](https://ifhover.github.io/leaf-ui/v/0.6.0/api/theme-tokens.md#leafthemetokens)。

## 使用深色模式

设置 `appearance: 'dark'` 即可；改回 `'light'` 恢复浅色：

```tsx
<ConfigProvider theme={{ appearance: 'dark' }}>
  <App />
</ConfigProvider>
```

组件的文字、背景和边框会一起切换。显式设置的 `primaryColor` 会保留原色；没有指定时使用该外观的默认主题色。

ConfigProvider 负责区域内组件的样式，不会给页面的 `body` 自动添加背景。业务页面的背景和文字也需要跟随外观时，可使用下文的 [CSS 变量](#在业务样式中使用主题)。

### 加一个切换开关

主题是普通 React 参数，可以用状态更新。打开下面的开关，查看卡片、按钮和文字一起切换：


深色模式保存更改

appearance.tsx

复制代码

```tsx lineNumbers file="../../src/examples/theming/appearance.tsx"
import { Button, Card, ConfigProvider, Flex, Switch } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function ThemeAppearance() {
  const [dark, setDark] = useState(false);

  return (
    <ConfigProvider theme={{ appearance: dark ? 'dark' : 'light' }}>
      <Card>
        <Flex direction="column" gap="md" align="start">
          <Switch checked={dark} onChange={(event) => setDark(event.target.checked)}>
            深色模式
          </Switch>
          <Button>保存更改</Button>
        </Flex>
      </Card>
    </ConfigProvider>
  );
}
```

展开代码

### 跟随系统外观

希望随操作系统切换时，使用 `useSystemAppearance`，并把结果传给 `theme.appearance`：

```tsx
import { ConfigProvider, useSystemAppearance } from '@ifhover/leaf-ui';

export function AppTheme() {
  const appearance = useSystemAppearance('light');

  return (
    <ConfigProvider theme={{ appearance }}>
      <App />
    </ConfigProvider>
  );
}
```

这里的 `'light'` 是首次渲染使用的外观，挂载后会读取并监听系统偏好。用户手动选择外观时，由应用保存选择并决定是否继续跟随系统。

## 只调整一个区域

嵌套一个 ConfigProvider，就能为某块内容设置独立主题。内层只覆盖写出的字段，其他配置继续继承：


全局蓝色

局部紫色

scoped.tsx

复制代码

```tsx lineNumbers file="../../src/examples/theming/scoped.tsx"
import { Button, ConfigProvider, Flex } from '@ifhover/leaf-ui';

export function ThemeScoped() {
  return (
    <ConfigProvider theme={{ primaryColor: '#1677ff', borderRadius: 8 }}>
      <Flex direction="column" gap="md" align="start">
        <Button>全局蓝色</Button>
        <ConfigProvider theme={{ primaryColor: '#7654c6' }}>
          <Button>局部紫色</Button>
        </ConfigProvider>
      </Flex>
    </ConfigProvider>
  );
}
```

展开代码

示例中两个按钮的基础圆角都是 8px，内层只把主题色改成紫色。从该区域打开的 Select 浮层、Modal，以及通过 `useConfirm`、`useMessage` 创建的反馈也会使用所在区域的主题。

## 调整控件尺寸和密度

只调整一个控件时，优先使用它的 `size="sm"` 或 `size="lg"`。要让整个区域的控件更紧凑，可以设置 ConfigProvider 的 `density`：

```tsx
<ConfigProvider density="compact">
  <App />
</ConfigProvider>
```

`density` 与 `theme` 同级。默认值为 `'comfortable'`；`'compact'` 会同时收紧控件、表单和浮层的间距，基础控件高度从 36px 调整为 30px，字号保持不变。

需要指定高度时再设置 `theme.controlHeight`，它优先于密度预设。例如 `controlHeight: 40` 会生成 34px / 40px / 46px 三种控件高度。尺寸对比见 [ConfigProvider](https://ifhover.github.io/leaf-ui/v/0.6.0/components/config-provider.md#%E5%9F%BA%E7%A1%80%E9%AB%98%E5%BA%A6)。

## 进阶定制

下面的配置适合已有明确设计要求的项目。只改颜色、圆角或外观时，使用前面的基础参数即可。

### 单独覆盖颜色或尺寸

`theme.tokens` 用于修改基础参数之外的具体样式。例如只调整成功色、大圆角和动效时长：

```tsx
import type { LeafTheme } from '@ifhover/leaf-ui';

const theme = {
  primaryColor: '#7654c6',
  borderRadius: 8,
  tokens: {
    successColor: '#20834a',
    borderRadiusLg: 18,
    motionDuration: 160,
  },
} satisfies LeafTheme;
```

将这个对象传给 `<ConfigProvider theme={theme}>`。这里的 `borderRadiusLg` 会覆盖自动生成的大圆角；`motionDuration` 的数字单位是毫秒。完整字段和说明见 [LeafThemeTokens](https://ifhover.github.io/leaf-ui/v/0.6.0/api/theme-tokens.md#leafthemetokens)。

如果使用很浅的主题色，可通过 `tokens.onPrimaryColor` 设置实色按钮上的文字色。自定义配色后，应检查正常、悬停和禁用状态的可读性。`motion: false` 可以关闭区域动效，系统的“减少动态效果”偏好始终优先。

### 只调整某类组件的样式

`theme.components` 按组件名称设置样式。例如让按钮使用 4px 圆角，同时调整卡片内边距：

```tsx
<ConfigProvider theme={{
  components: {
    Button: { borderRadius: 4 },
    Card: { padding: 24 },
  },
}}>
  <App />
</ConfigProvider>
```

可用样式字段见 [LeafComponentTokens](https://ifhover.github.io/leaf-ui/v/0.6.0/api/theme-tokens.md#leafcomponenttokens)，具体组件支持的字段以其文档为准。

这里的 `theme.components` 调整样式。如果想统一按钮的 `size`、`variant` 或其他组件参数，使用 ConfigProvider 上的 `components`，见 [组件默认值](https://ifhover.github.io/leaf-ui/v/0.6.0/components/config-provider.md#%E7%BB%84%E4%BB%B6%E9%BB%98%E8%AE%A4%E5%80%BC)。

### 在业务样式中使用主题

ConfigProvider 会在它包裹的区域提供 `--leaf-*` CSS 变量。业务内容位于该区域内时，可以读取当前主题，随颜色和外观一起更新：

```tsx
<ConfigProvider theme={{ appearance: 'dark' }}>
  <section className="app-panel">业务内容</section>
</ConfigProvider>
```

```css
.app-panel {
  padding: 16px;
  color: var(--leaf-color-text);
  background: var(--leaf-color-surface);
  border: 1px solid var(--leaf-color-border);
  border-radius: var(--leaf-radius);
}
```

| 常用变量                                                  | 用途           |
| ----------------------------------------------------- | ------------ |
| `--leaf-color-primary`                                | 当前主题色。       |
| `--leaf-color-on-primary`                             | 实色主题背景上的文字色。 |
| `--leaf-color-text` / `--leaf-color-text-muted`       | 主要、次要文字色。    |
| `--leaf-color-surface` / `--leaf-color-surface-muted` | 内容背景、辅助背景。   |
| `--leaf-color-border`                                 | 边框颜色。        |
| `--leaf-radius`                                       | 基础圆角。        |

调整 Leaf UI 组件的主题仍通过 ConfigProvider，业务 CSS 用这些变量读取结果。仅修改某个基础 CSS 变量，不会重新生成整套交互颜色。

使用 Tailwind CSS 时，可直接引入包提供的配置，通过 `bg-leaf-surface`、`text-leaf-primary` 等工具类复用主题。Tailwind 3 / 4 的接入方式见 [Tailwind CSS](https://ifhover.github.io/leaf-ui/v/0.6.0/guide/tailwindcss.md)。

## 服务端渲染

服务端和客户端首次渲染应使用相同的外观。需要记住用户选择时，可由服务端读取 Cookie 并传入初始值；使用系统外观时，挂载后再更新。

主题色优先传入具体的 HEX、RGB 或 HSL 颜色。`var(--brand-color)` 需要在浏览器挂载后解析，不能保证服务端首屏就得到对应的派生颜色。

安装见 [安装&快速开始](https://ifhover.github.io/leaf-ui/v/0.6.0/guide/getting-started.md)，Next.js 等框架的接入见 [服务端渲染](https://ifhover.github.io/leaf-ui/v/0.6.0/guide/ssr.md)，支持范围见 [浏览器兼容性](https://ifhover.github.io/leaf-ui/v/0.6.0/guide/compatibility.md)。