---
url: /utils/theme-color.md
---
# 主题与颜色

运行时主题工具：主色切换、色阶生成、颜色解析混合。全部从包根导出：

```js
import { setPrimaryColor, generatePrimaryRamp, mixHex } from '@wil-works/evoke-business-ui'
```

## setPrimaryColor — 运行时主色

传入十六进制主色，立即重写 `--eb-color-primary` 及 7 档色阶（`--eb-color-primary-light-N` / `dark-2`），图表色板（Chart 系列）同步跟随。**无需刷新页面**：

::: warning 全局副作用
`setPrimaryColor` / `setDensity` 作用于 `documentElement`，影响整页。组件树内推荐用 [ConfigProvider](/components/config-provider) 的 `theme-color` / `density` 属性声明式下发。
:::

## generatePrimaryRamp — 色阶生成

由主色派生全部 7 档梯度令牌（`dark-2`、`base`、`light-3/5/7/8/9`，sRGB 线性混合：light-N 向白混合 N×10%，dark-2 向黑混合 20%），与 `variables.css` 手调梯度同一算法。**点击上方主色，下方梯度实时重算**：

## 颜色解析与混合

`normalizeHex` / `hexToRgb` / `rgbToHex` / `mixHex` 四件套，容错输入、不抛错：

## 密度与头像色

`setDensity` 作用于 `html[data-eb-density]`，切换**整页所有按钮/输入框的高度**：default 32px → compact 28px → loose 36px（循环），按钮上实时显示当前档位与控件高度：

## API

| 函数 | 类型 | 说明 |
| --- | --- | --- |
| setPrimaryColor | `(hex: string, target?: HTMLElement) => void` | 重写主色与色阶 CSS 变量；默认作用于 documentElement |
| generatePrimaryRamp | `(hex: string) => Record<string, string> \| null` | 返回 `{ '--eb-color-primary': …, '-light-3': …, '-rgb': 'r, g, b' }` 令牌表 |
| normalizeHex | `(hex: unknown) => string \| null` | 容错归一化为 `#RRGGBB`；非法返回 null |
| hexToRgb | `(hex: string) => { r, g, b } \| null` | — |
| rgbToHex | `(r, g, b) => string` | — |
| mixHex | `(a, b, t: number) => string \| null` | t=0 返回 a，t=1 返回 b |
| setDensity / getDensity | `(mode) => void` / `() => string` | `html[data-eb-density]` |
| avatarColor | `(str: string) => string` | 字符串哈希 → 稳定色值 |