深入解析 Mantine 官方调色板生成组件 @mantinex/colors-generator:源码算法与应用实践
深入解析 Mantine 官方调色板生成组件 @mantinex/colors-generator:源码算法与应用实践
本指南以仓库内 packages/@mantinex/colors-generator/README.md 为骨架,结合其组件源码、依赖的 @mantine/colors-generator 算法以及官方站点 mantine.dev 的实际使用方式,为你完整剖析「Colors generator 组件」——从安装、核心组件结构,到 10 级色阶生成算法(含 WCAG 对比度约束),再到把生成结果接入 MantineProvider 主题的完整落地流程。读完本文,你将理解 Mantine 调色板的生成原理,并能独立复刻一个自己的颜色生成工具。
一、组件是什么
@mantinex/colors-generator 是 Mantine 仓库内 packages/@mantinex 系列下的一个工具型组件包,官方定位为 “Colors generator component”。它不参与 Mantine 核心组件的渲染,而是作为 Mantine 生态的「调色板生成器」:给定一个基准颜色,自动生成一组从浅到深的 10 级色阶,并直接以 ColorSwatch 色块 + 十六进制色值 + 对比度数值的可视化形式呈现,便于设计者预览、校验并最终把结果贴进 createTheme。
该包在仓库中的完整结构如下:
packages/@mantinex/colors-generator/
├── README.md
├── package.json
└── src/
├── index.ts
└── ColorsGenerator/
├── ColorsGenerator.tsx # 主组件:ColorInput + 两段 ColorsList
├── ColorsGenerator.story.tsx # Storybook 演示
├── ColorsList/ColorsList.tsx # 色阶列表渲染(含对比度展示)
└── generate-colors-shades.ts # 10 级色阶生成算法(chroma-js)
二、安装与依赖要求
按照官方 README 的说明,安装方式为:
# With yarn
yarn add @mantinex/colors-generator
# With npm
npm install @mantinex/colors-generator
从 package.json 可以看到它的运行时依赖约束(peerDependencies):
@mantine/core >= 7.0.0:组件内部使用了ColorInput、ColorSwatch、Group、Text等核心组件;@mantine/hooks >= 7.0.0:按声明需要 hooks 支持;react与react-dom:仓库当前锁定^19.2.0;- 运行时会用到
chroma-js完成颜色运算(见下文源码)。
包的发布产物同时提供 ESM(./esm/index.mjs)、CJS(./cjs/index.cjs)与类型声明(./lib/index.d.ts),并导出 ./styles.css 与 ./styles.layer.css 样式文件。因此在实际项目中使用时,通常需要与 Mantine v7 及以上版本配合,并确保样式被正确引入。
三、核心组件结构
3.1 主组件 ColorsGenerator
主组件 ColorsGenerator.tsx 的实现非常精简:
import { useState } from 'react';
import { ColorInput } from '@mantine/core';
import { ColorsList } from './ColorsList/ColorsList';
import { generateColorShades } from './generate-colors-shades';
const reference = [
'#e5f4ff', '#cde2ff', '#9bc2ff', '#64a0ff', '#3984fe',
'#1d72fe', '#0969ff', '#0058e4', '#004ecc', '#0043b5',
];
export function ColorsGenerator() {
const [color, setColor] = useState('#000000');
return (
<div>
<ColorInput value={color} onChange={setColor} mb="md" size="lg" radius="md" />
<ColorsList colors={reference} />
<ColorsList colors={generateColorShades(color)} />
</div>
);
}
要点拆解:
- 内部维护一个
colorstate,默认值为#000000; - 通过 Mantine 的
ColorInput让用户自由选择或输入任意 hex 颜色,onChange直接更新 state; - 第一段
ColorsList展示一个内置的蓝色reference参考色阶(对应 Mantine 官方蓝色调色板),用于和生成结果做视觉对比; - 第二段
ColorsList展示generateColorShades(color)实时生成的 10 级色阶,实现「所见即所得」的调色体验。
3.2 色阶渲染 ColorsList
ColorsList.tsx 负责把色阶数组渲染成可视化列表,它接收两个 props:
export interface ColorsListProps {
colors: string[]; // hex 色值数组
withSample?: boolean; // 是否额外展示 SAMPLE LIGHT / SAMPLE DARK 预览块
}
每个色块使用 Mantine 的 ColorSwatch(size={100}、无圆角、无阴影)渲染,下方用等宽字体(ff="monospace")标注 index: #hex,并且实时计算该色与纯白的对比度:
const contrast = chroma.contrast(color, '#fff');
// 对比度 < 4.5 时显示为红色,否则显示为绿色
<Text span inherit fw="bold" c={contrast < 4.5 ? 'red' : 'green'}>
{contrast.toFixed(2)}
</Text>
这是一个非常实用的细节:4.5 正是 WCAG AA 标准对正文文本与背景的最小对比度要求。组件直接以色块+数值告诉你哪些色阶用作白字背景是安全的(绿色),哪些不安全(红色)。withSample 开启时还会额外渲染两个 200×60 的样例条:一个使用 colors[6] 作为背景(SAMPLE LIGHT 语义,即主色阶),一个使用 colors[8](SAMPLE DARK),用于直观预览深色场景下的可读性。
四、色阶生成算法(核心原理)
@mantinex/colors-generator 的价值核心在 generate-colors-shades.ts,它是一个基于 chroma-js 的纯函数:
import chroma from 'chroma-js';
export function generateColorShades(hexColor: string): string[] {
const base = chroma(hexColor);
let shade6: chroma.Color | null = null;
for (let l = 0.8; l >= 0.2; l -= 0.001) {
const candidate = base.set('hsl.l', l);
const contrast = chroma.contrast(candidate, '#fff');
if (contrast >= 4.5 && contrast <= 4.55) {
shade6 = candidate;
break;
}
}
if (!shade6) {
let best: chroma.Color = base.set('hsl.l', 0.2);
let bestContrast = 0;
for (let l = 0.8; l >= 0.2; l -= 0.001) {
const candidate = base.set('hsl.l', l);
const contrast = chroma.contrast(candidate, '#fff');
if (contrast < 4.5 && contrast > bestContrast) {
best = candidate;
bestContrast = contrast;
}
}
shade6 = best;
}
const lightest = base.set('hsl.l', 0.97).hex();
const darkest = base.set('hsl.l', 0.36).hex();
const scale = chroma.scale([lightest, shade6.hex(), darkest]).mode('rgb');
return Array.from({ length: 10 }, (_, i) => scale(i / 9).hex());
}
函数注释明确定义了算法约束,逐条解读如下:
- 生成 10 个从浅到深的色阶,索引 0 最浅、9 最深;
- shade[6] 与纯白的对比度恒定在 4.5 ~ 4.55 之间(且绝不高于 4.55):这是算法最精巧的设计。它从 HSL 亮度
l=0.8向下以 0.001 步长扫描,找到第一个对比度落在 [4.5, 4.55] 区间的候选色作为主色阶shade6。这样 Mantine 约定俗成的「6 号位主色」在任何色相下都能保证白字可读(满足 WCAG AA); - 容错分支:如果某些极端颜色(例如特别暗的颜色)在扫描区间内找不到满足条件的亮度,就退而求其次,选取对比度
< 4.5但最接近 4.5 的候选作为shade6,保证函数永远有返回结果; - 最浅与最深色阶由颜色自身推导,而非强制拉白/拉黑:
lightest是亮度 0.97 的极浅色,darkest是亮度 0.36 的深色,二者都保留原色相与饱和度信息,避免了 Mantine 官方调色板常见的「首尾两阶趋向纯白/纯黑」现象; - 最终使用
chroma.scale([lightest, shade6, darkest]).mode('rgb')在 RGB 模式下线性插值,均匀取 10 个点(i/9),得到连续平滑的色阶过渡。
这一算法在仓库中被同步用于生成 Mantine 默认主题色板:packages/@mantine/colors-generator/src/generate-colors.ts 中定义了 LIGHTNESS_MAP = [0.96, 0.907, 0.805, 0.697, 0.605, 0.547, 0.518, 0.445, 0.395, 0.34] 与 SATURATION_MAP,通过「就近亮度 + 饱和度微调」的方式生成标准 10 元组 MantineColorsTuple——两者思路一致(都是围绕 HSL 亮度做文章),但 @mantinex 版本更聚焦「保证 6 号位对比度达标」这一硬性约束。
五、在 Storybook 中查看演示
仓库为组件提供了 Story 文件 ColorsGenerator.story.tsx,其中内置了多组官方调色板示例(blue、indigo、red、pink、grape 的 10 级色阶),并导出一个 Usage 演示,把这些色阶通过 ColorsList 批量渲染,方便在 Storybook 中直观对比不同色相下的色阶过渡与对比度表现:
export function Usage() {
const lists = Object.values(colors).map((colors, index) => (
<ColorsList key={index} colors={colors} />
));
return <div style={{ padding: 40 }}>{lists}</div>;
}
你可以在仓库中执行 Storybook 相关脚本,或在对应组件目录下运行开发服务来查看这些演示。
六、官方站点中的完整应用:从「生成」到「接入主题」
@mantinex/colors-generator 本身提供的是生成与预览组件;而把生成结果真正用起来,可以参考 Mantine 官方站点 mantine.dev 中的 ColorsGenerator 页面实现(apps/mantine.dev/src/components/ColorsGenerator/ColorsGenerator.tsx),它展示了完整的「生成 → 预览 → 输出代码」链路:
- 颜色输入:使用
ColorInput,并支持 URL 参数?color=#5474B4直接定位颜色(useEffect中通过正则/^#[0-9A-F]{6}$/i校验合法性后同步到 state); - 生成色阶:调用
@mantine/colors-generator的generateColorsMap(color),得到{ colors, baseColorIndex },其中baseColorIndex标记基准色落在色阶中的位置; - 组件预览:
ComponentsPreview用生成的颜色渲染真实的 Mantine 组件样例,直观检验观感; - 输出代码:
ColorsOutput(ColorsOutput.tsx)直接生成两段可复制代码:
- 纯色阶数组(JSON 格式的 10 个 hex 值);
- 接入主题的完整示例:
import { MantineProvider, createTheme, MantineColorsTuple } from '@mantine/core';
const myColor: MantineColorsTuple = [
'#e5f4ff', '#cde2ff', '#9bc2ff', '#64a0ff', '#3984fe',
'#1d72fe', '#0969ff', '#0058e4', '#004ecc', '#0043b5',
];
const theme = createTheme({
colors: {
myColor,
},
primaryColor: 'myColor',
});
function Demo() {
return (
<MantineProvider theme={theme}>
{/* Your app here */}
</MantineProvider>
);
}
官方页面还内置了 26 个预设色(见 colors-preset.ts,如 Blue gray #63687C、Tomato #F06418、Bright green #6BD731、Pale blue #5474B4 等),方便快速挑选起始色。
实际落地三步走
结合以上源码,将生成的色阶接入你自己的 Mantine 应用只需三步:
- 通过
@mantinex/colors-generator的generateColorShades(color)(或在站点页面复制色阶数组)拿到 10 个 hex 值; - 声明一个
MantineColorsTuple类型变量并填入色阶数组; - 在
createTheme的colors中注册该颜色,并将其设置为primaryColor,此后按钮、链接、焦点态等所有主色相关组件都会自动使用新调色板。
七、小结
@mantinex/colors-generator 是 Mantine 生态中一个短小精悍但设计讲究的工具组件:输入一个颜色,输出一组经过 WCAG 对比度约束、过渡平滑的 10 级色阶,并以可视化方式标注每个色阶的白字对比度。其核心算法(generate-colors-shades.ts)通过对 HSL 亮度的精细扫描与 chroma-js 插值,保证了「6 号位主色 + 白字」始终满足 4.5:1 的可用性底线;结合官方站点的完整链路,你可以轻松把生成结果接入 MantineProvider,为应用打造一套既美观又符合可访问性标准的自定义主题色。