Mantine colors-generator 使用指南基于单一颜色值生成 10 阶调色板【免费下载链接】mantineA fully featured React components library项目地址: https://gitcode.com/GitHub_Trending/ma/mantinemantine/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 dependencychroma-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 CJSsideEffects标记为false可被 tree-shaking 安全优化许可证为 MIT可自由用于商业项目。核心 APIgenerateColors 与 generateColorsMap整个包的实现集中在一个文件 src/generate-colors.ts 中共导出两套 APIgenerateColors最常用的函数接收一个颜色字符串返回一个Mantine 颜色元组10 个 HEX 色阶import { generateColors } from mantine/colors-generator; const palette generateColors(#375EAC); // palette 为形如 [#EBF0FA, #D4E0F2, ..., #1B2D56] 的 10 元素数组其返回类型为MantineColorsTuple定义如下见 generate-colors.tsexport 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.tsximport { generateColorsMap } from mantine/colors-generator; const { colors, baseColorIndex } generateColorsMap(#375EAC); // colors: chroma.Color[]10 个 chroma 颜色对象 // baseColorIndex: 输入颜色在色板中落位的索引0-9colors包含 10 个chroma-js Color 对象需要时可调用.hex()、.hsl()等方法转换为具体格式baseColorIndex输入颜色原始值未做明度/饱和度调整在色板中的索引位置。官方在线工具正是利用它高亮输入色对应的那一格色阶。算法原理HSL 明度映射 饱和度补偿生成逻辑并不复杂核心思想是保持色相hue不变把输入颜色映射到一条预设的明度阶梯上再按位置对饱和度做微调以保证色板从浅到深过渡自然。源码依赖两个硬编码映射表generate-colors.tsconst 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];完整流程分四步解析颜色chroma(color)将任意支持的格式HEX、RGB、HSL、OKLCH 等统一解析为 chroma 颜色对象定位基准索引getClosestLightness计算输入颜色在 HSL 空间下的明度hsl.l并从LIGHTNESS_MAP中选出差值最小的明度值得到baseColorIndex重写明度把输入颜色的明度依次替换为LIGHTNESS_MAP中的 10 个值得到 10 个明度不同的同色相颜色饱和度补偿对每个色阶计算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 等中使用colorpale-blue或按索引引用如colorpale-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: RecordExtendedCustomColors, MantineColorsTuple; } }使用注意事项与适用边界浅色效果欠佳官方文档明确提示generateColors对深色蓝、紫、红效果最佳对浅色黄、青、橙生成的色板可能对比度不足。原因是固定明度阶梯对浅色输入的区分度有限且饱和度补偿在浅色区间表现不稳定。因此官方建议尽量预先在构建期生成色板如把结果直接写进主题配置避免运行时反复计算与潜在的对比度问题如果输入色很浅可先手动挑选更深的基准色再配合 colorsTuple 工具 将单一颜色铺满 10 个色阶colorsTuple(#FFC0CB)作为替代方案。需要 chroma-js算法直接依赖chroma-jspeerDependency2.4.2安装时必须一并安装否则运行时import chroma from chroma-js会因缺少依赖而报错。在线工具官方还提供了基于同一算法的在线配色器在 mantine.dev 的/colors-generator页面源码位于 apps/mantine.dev/src/components/ColorsGenerator它通过useLocalStorage记住你上次使用的颜色、支持#RRGGBBURL 参数直达并实时预览生成的 10 色阶在各组件上的效果适合在编码前快速挑选色板。小结mantine/colors-generator以极小的 API 面两个函数 一个类型解决了 Mantine 主题定制中最繁琐的补全 10 色阶问题generateColors直接产出可在theme.colors中使用的 HEX 元组generateColorsMap则提供更底层的 chroma 颜色对象与基准索引供高级场景使用。理解其明度阶梯映射 饱和度对称补偿的算法后你既能放心地把品牌色动态接入主题也能预判浅色输入的对比度风险在主题工程化时做出合理取舍。【免费下载链接】mantineA fully featured React components library项目地址: https://gitcode.com/GitHub_Trending/ma/mantine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考