深入解析 Mantine 官方调色板生成组件 @mantinex/colors-generator:源码算法与应用实践

原创2026-09-09 21:06:221,762 阅读
文章标签:前端UI组件设计系统富文本图表库

深入解析 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>
  );
}

要点拆解:

  • 内部维护一个 color state,默认值为 #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());
}

函数注释明确定义了算法约束,逐条解读如下:

  1. 生成 10 个从浅到深的色阶,索引 0 最浅、9 最深;
  2. shade[6] 与纯白的对比度恒定在 4.5 ~ 4.55 之间(且绝不高于 4.55):这是算法最精巧的设计。它从 HSL 亮度 l=0.8 向下以 0.001 步长扫描,找到第一个对比度落在 [4.5, 4.55] 区间的候选色作为主色阶 shade6。这样 Mantine 约定俗成的「6 号位主色」在任何色相下都能保证白字可读(满足 WCAG AA);
  3. 容错分支:如果某些极端颜色(例如特别暗的颜色)在扫描区间内找不到满足条件的亮度,就退而求其次,选取对比度 < 4.5 但最接近 4.5 的候选作为 shade6,保证函数永远有返回结果;
  4. 最浅与最深色阶由颜色自身推导,而非强制拉白/拉黑:lightest 是亮度 0.97 的极浅色,darkest 是亮度 0.36 的深色,二者都保留原色相与饱和度信息,避免了 Mantine 官方调色板常见的「首尾两阶趋向纯白/纯黑」现象;
  5. 最终使用 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),它展示了完整的「生成 → 预览 → 输出代码」链路:

  1. 颜色输入:使用 ColorInput,并支持 URL 参数 ?color=#5474B4 直接定位颜色(useEffect 中通过正则 /^#[0-9A-F]{6}$/i 校验合法性后同步到 state);
  2. 生成色阶:调用 @mantine/colors-generator 的 generateColorsMap(color),得到 { colors, baseColorIndex },其中 baseColorIndex 标记基准色落在色阶中的位置;
  3. 组件预览:ComponentsPreview 用生成的颜色渲染真实的 Mantine 组件样例,直观检验观感;
  4. 输出代码: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 应用只需三步:

  1. 通过 @mantinex/colors-generator 的 generateColorShades(color)(或在站点页面复制色阶数组)拿到 10 个 hex 值;
  2. 声明一个 MantineColorsTuple 类型变量并填入色阶数组;
  3. 在 createTheme 的 colors 中注册该颜色,并将其设置为 primaryColor,此后按钮、链接、焦点态等所有主色相关组件都会自动使用新调色板。

七、小结

@mantinex/colors-generator 是 Mantine 生态中一个短小精悍但设计讲究的工具组件:输入一个颜色,输出一组经过 WCAG 对比度约束、过渡平滑的 10 级色阶,并以可视化方式标注每个色阶的白字对比度。其核心算法(generate-colors-shades.ts)通过对 HSL 亮度的精细扫描与 chroma-js 插值,保证了「6 号位主色 + 白字」始终满足 4.5:1 的可用性底线;结合官方站点的完整链路,你可以轻松把生成结果接入 MantineProvider,为应用打造一套既美观又符合可访问性标准的自定义主题色。

登录后查看全文
mantine