Mantine colors-generator 使用指南:基于单一颜色值生成 10 阶调色板

原创2026-09-09 22:02:281,957 阅读
文章标签:前端UI组件设计系统富文本图表库

Mantine colors-generator 使用指南:基于单一颜色值生成 10 阶调色板

@mantine/colors-generator 是 Mantine 生态中用于根据一个颜色值自动生成 10 个色阶调色板的轻量工具包。它服务于 Mantine 主题系统(theme.colors 要求每种颜色至少提供 10 个深浅不同的色阶),适合在应用内动态生成品牌色、主题色,或在开发阶段快速为自定义颜色补齐完整色板。读完本文,你将掌握该包的安装方式、两个核心导出函数(generateColors / generateColorsMap)的用法、底层算法原理,以及如何将生成结果接入 MantineProvider 的 theme.colors 完成自定义主题配置。

包简介与安装

@mantine/colors-generator 是 Mantine 官方仓库中独立发布的子包,版本与 Mantine 主库同步(当前仓库内为 9.6.0)。其定位在 package.json 中描述为 "A library to generate 10 shades of color based on provided color value",即输入任意一个 CSS 颜色值,输出一组包含 10 个色阶的颜色数组。

安装时除包本身外,还需安装其 peer dependency chroma-js(版本要求 >=2.4.2),因为算法基于 chroma-js 的颜色解析与 HSL 变换能力:

# With yarn
yarn add @mantine/colors-generator chroma-js

# With npm
npm install @mantine/colors-generator chroma-js

包的导出入口在 src/index.ts,公开了两个函数:generateColors 与 generateColorsMap。该包采用双格式发布(ESM + CJS),sideEffects 标记为 false,可被 tree-shaking 安全优化;许可证为 MIT,可自由用于商业项目。

核心 API:generateColors 与 generateColorsMap

整个包的实现集中在一个文件 src/generate-colors.ts 中,共导出两套 API:

generateColors

最常用的函数,接收一个颜色字符串,返回一个 Mantine 颜色元组(10 个 HEX 色阶):

import { generateColors } from '@mantine/colors-generator';

const palette = generateColors('#375EAC');
// palette 为形如 ['#EBF0FA', '#D4E0F2', ..., '#1B2D56'] 的 10 元素数组

其返回类型为 MantineColorsTuple,定义如下(见 generate-colors.ts):

export type MantineColorsTuple = readonly [
  string, // 索引 0(最浅)
  string, // 索引 1
  string, // 索引 2
  string, // 索引 3
  string, // 索引 4
  string, // 索引 5
  string, // 索引 6
  string, // 索引 7
  string, // 索引 8
  string, // 索引 9(最深)
  ...string[], // 允许更多色阶(Mantine 组件默认使用前 10 个)
];

注意返回值带有 as unknown as MantineColorsTuple 类型断言,因为运行时只是 string[] 的映射结果;类型约束的意义在于保证与 theme.colors 的类型系统兼容。

generateColorsMap

返回结构更丰富的中间结果,适合需要定位"哪个色阶最接近输入颜色"的场景(官方在线配色工具的交互预览正是基于它实现,见 ColorsGenerator.tsx):

import { generateColorsMap } from '@mantine/colors-generator';

const { colors, baseColorIndex } = generateColorsMap('#375EAC');
// colors: chroma.Color[](10 个 chroma 颜色对象)
// baseColorIndex: 输入颜色在色板中落位的索引(0-9)
  • colors:包含 10 个 chroma-js Color 对象,需要时可调用 .hex()、.hsl() 等方法转换为具体格式;
  • baseColorIndex:输入颜色原始值(未做明度/饱和度调整)在色板中的索引位置。官方在线工具正是利用它高亮"输入色"对应的那一格色阶。

算法原理:HSL 明度映射 + 饱和度补偿

生成逻辑并不复杂,核心思想是:保持色相(hue)不变,把输入颜色映射到一条预设的明度阶梯上,再按位置对饱和度做微调,以保证色板从浅到深过渡自然。源码依赖两个硬编码映射表(generate-colors.ts):

const LIGHTNESS_MAP = [0.96, 0.907, 0.805, 0.697, 0.605, 0.547, 0.518, 0.445, 0.395, 0.34];
const SATURATION_MAP = [0.32, 0.16, 0.08, 0.04, 0, 0, 0.04, 0.08, 0.16, 0.32];

完整流程分四步:

  1. 解析颜色:chroma(color) 将任意支持的格式(HEX、RGB、HSL、OKLCH 等)统一解析为 chroma 颜色对象;
  2. 定位基准索引:getClosestLightness 计算输入颜色在 HSL 空间下的明度(hsl.l),并从 LIGHTNESS_MAP 中选出差值最小的明度值,得到 baseColorIndex;
  3. 重写明度:把输入颜色的明度依次替换为 LIGHTNESS_MAP 中的 10 个值,得到 10 个明度不同的同色相颜色;
  4. 饱和度补偿:对每个色阶,计算 SATURATION_MAP[i] - SATURATION_MAP[baseColorIndex] 的差值——差值为正则 saturate(delta) 提高饱和度,为负则 desaturate(-delta) 降低饱和度。这一步是为了让中间色阶(靠近输入颜色)饱和度归零、两端略微饱和,从而让色板整体更均衡。

最后,第 baseColorIndex 位会被直接替换为输入颜色的原始值(colors[baseColorIndex] = chroma(color)),确保你输入的颜色以最接近的明度档位原样出现在色板中。generateColors 内部就是调用 generateColorsMap(color).colors.map((c) => c.hex()) 得到最终 HEX 数组。

实战接入:把生成色板挂到 Mantine 主题

Mantine 的 theme.colors 要求每种颜色至少包含 10 个色阶(否则 TS 报错、部分组件变体取不到正确颜色)。生成器正好用来补齐这个结构。官方文档的推荐用法如下(见 Colors generation 章节):

import { generateColors } from '@mantine/colors-generator';
import { MantineProvider } from '@mantine/core';

function Demo() {
  return (
    <MantineProvider
      theme={{
        colors: {
          'pale-blue': generateColors('#375EAC'),
        },
      }}
    >
      {/* 你的应用 */}
    </MantineProvider>
  );
}

接入后即可在所有支持 color 属性的组件(Button、Badge、Switch、Alert 等)中使用 color="pale-blue",或按索引引用如 color="pale-blue.5";同时 Mantine 会自动将其暴露为 CSS 变量(如 --mantine-color-pale-blue-5)。

若需要把生成结果与 Mantine 的类型系统打通(让自定义色名获得 TS 自动补全),可在项目中增加类型声明:

import { DefaultMantineColor, MantineColorsTuple } from '@mantine/core';

type ExtendedCustomColors = 'pale-blue' | DefaultMantineColor;

declare module '@mantine/core' {
  export interface MantineThemeColorsOverride {
    colors: Record<ExtendedCustomColors, MantineColorsTuple>;
  }
}

使用注意事项与适用边界

浅色效果欠佳:官方文档明确提示,generateColors 对深色(蓝、紫、红)效果最佳;对浅色(黄、青、橙)生成的色板可能对比度不足。原因是固定明度阶梯对浅色输入的区分度有限,且饱和度补偿在浅色区间表现不稳定。因此官方建议:

  • 尽量预先在构建期生成色板(如把结果直接写进主题配置),避免运行时反复计算与潜在的对比度问题;
  • 如果输入色很浅,可先手动挑选更深的基准色,再配合 colorsTuple 工具 将单一颜色铺满 10 个色阶(colorsTuple('#FFC0CB'))作为替代方案。

需要 chroma-js:算法直接依赖 chroma-js(peerDependency >=2.4.2),安装时必须一并安装,否则运行时 import chroma from 'chroma-js' 会因缺少依赖而报错。

在线工具:官方还提供了基于同一算法的在线配色器(在 mantine.dev 的 /colors-generator 页面,源码位于 apps/mantine.dev/src/components/ColorsGenerator),它通过 useLocalStorage 记住你上次使用的颜色、支持 #RRGGBB URL 参数直达,并实时预览生成的 10 色阶在各组件上的效果,适合在编码前快速挑选色板。

小结

@mantine/colors-generator 以极小的 API 面(两个函数 + 一个类型)解决了 Mantine 主题定制中最繁琐的"补全 10 色阶"问题:generateColors 直接产出可在 theme.colors 中使用的 HEX 元组,generateColorsMap 则提供更底层的 chroma 颜色对象与基准索引供高级场景使用。理解其"明度阶梯映射 + 饱和度对称补偿"的算法后,你既能放心地把品牌色动态接入主题,也能预判浅色输入的对比度风险,在主题工程化时做出合理取舍。

登录后查看全文
mantine