@builden/bd-color

v1.0.1

Published

18 days ago

一个 TypeScript 编写的颜色处理工具包，支持多种颜色格式转换、调色板生成和预设颜色。

0High
0Medium
0Low

builden

bd-color

一个 TypeScript 编写的颜色处理工具包，支持多种颜色格式转换、调色板生成和预设颜色。

安装

npm install @builden/bd-color
# 或
bun add @builden/bd-color

核心功能

Color 类 - 颜色创建、格式转换、颜色操作
调色板生成 - Ant Design / Tailwind CSS / OKLCH 三种算法
预设颜色 - Ant Design + Tailwind CSS 预设调色板
消费级 helper - normalizeHexColor / hexToRgb / rgbToHex / alpha / mix / lighten / darken / tint / shade / toRgb / toHex

导入方式

import {
  Color,
  generate,
  generatePalette,
  normalizeHexColor,
  hexToRgb,
  rgbToHex,
  alpha,
  mix,
  lighten,
  darken,
  tint,
  shade,
  toRgb,
  toHex,
} from '@builden/bd-color';

import { generateAntDesign, generateTailwind } from '@builden/bd-color/generate';
import { alpha as alphaOnly, mix as mixOnly } from '@builden/bd-color/operations';

根入口适合大多数消费场景
@builden/bd-color/operations 适合只用颜色转换与混合的场景
@builden/bd-color/generate 适合只取调色板生成算法的场景
包已经标记为 sideEffects: false，可以正常 tree-shake

Color 类

创建颜色

支持多种方式创建颜色：

import { Color } from '@builden/bd-color';

// 从 Hex 字符串创建
const color1 = new Color('#ff5500');
const color2 = new Color('#f50'); // 3位简写
const color3 = new Color('#ff550080'); // 8位带透明度

// 从 RGB/HSL/HSV 对象创建
const color4 = new Color({ r: 255, g: 85, b: 0 });
const color5 = new Color({ h: 24, s: 100, l: 50 });
const color6 = new Color({ h: 24, s: 100, v: 100 });

// 从 OKLCH/OKLAB 创建 (现代色彩空间)
const color7 = new Color({ l: 0.6, c: 0.15, h: 24 });
const color8 = new Color({ l: 0.6, a: 0.1, b: 0.15 });

// 从 CSS 字符串创建
const color9 = new Color('rgb(255, 85, 0)');
const color10 = new Color('hsl(24, 100%, 50%)');
const color11 = new Color('rgba(255, 85, 0, 0.5)');

// 从颜色名称创建
const color12 = new Color('red');
const color13 = new Color('blue');

格式转换

const color = new Color('#ff5500');

// 转换为 Hex 字符串
color.toHexString(); // "#ff5500"

// 转换为 RGB 对象
color.toRgb(); // { r: 255, g: 85, b: 0, a: 1 }

// 转换为 RGB 字符串
color.toRgbString(); // "rgb(255,85,0)"
color.toRgbString(); // 带透明度: "rgba(255,85,0,0.5)"

// 转换为 HSL
color.toHsl(); // { h: 24, s: 100, l: 50, a: 1 }

// 转换为 HSL 字符串
color.toHslString(); // "hsl(24,100%,50%)"

// 转换为 HSV
color.toHsv(); // { h: 24, s: 100, v: 100, a: 1 }

// 转换为 OKLAB (现代感知均匀色彩空间)
color.toOklab(); // { l: 0.6, a: 0.1, b: 0.15, alpha: 1 }

// 转换为 OKLCH (极坐标形式)
color.toOklch(); // { l: 0.6, c: 0.15, h: 24, a: 1 }

颜色操作

const color = new Color('#ff5500');

// 调整亮度
color.lighten(10); // 变亮 10%
color.darken(10); // 变暗 10%

// 调整饱和度
color.saturate(10); // 增加饱和度 10%
color.desaturate(10); // 减少饱和度 10%

// 混合颜色
color.mix('#000000', 50); // 与黑色混合 50%
color.mix('#ffffff', 30); // 与白色混合 30%

// 调色 (Tint = 混合白色, Shade = 混合黑色)
color.tint(20); // 添加 20% 白色
color.shade(20); // 添加 20% 黑色

// 兼容 helper 语义
// bd-color 的 lighten / darken 是 HSL lightness 调整
// 如果要保持设计系统里常见的“混白 / 混黑”语义，请优先使用 tint / shade

// 灰度转换
color.grayscale(); // 转换为灰度颜色

// 计算对比度 (WCAG 标准)
color.contrast('#000000'); // 与黑色对比度
color.contrast('blue'); // 与蓝色对比度

// 克隆颜色
color.clone();

状态判断

const color = new Color('#ff5500');

// 判断颜色明暗
color.isDark(); // 是否为深色
color.isLight(); // 是否为浅色

// 判断颜色是否相等
const color2 = new Color('#ff5500');
color.equals(color2); // true

// 获取亮度值 (0-255)
color.getBrightness();

// 获取相对亮度 (用于计算对比度)
color.getLuminance();

Helper 说明

import {
  normalizeHexColor,
  hexToRgb,
  rgbToHex,
  alpha,
  mix,
  lighten,
  darken,
  tint,
  shade,
  toRgb,
  toHex,
  generatePalette,
} from '@builden/bd-color';

normalizeHexColor('1677ff'); // "#1677ff"
hexToRgb('#1677ff'); // { r: 22, g: 119, b: 255 }
rgbToHex({ r: 22, g: 119, b: 255 }); // "#1677ff"
generatePalette('#1677ff'); // 1-10 的 Ant Design 风格调色板

调色板生成

Ant Design 算法

生成 Ant Design 风格的 10 色阶调色板，主色位于 index 5：

import { generateAntDesign, generate, Color } from '@builden/bd-color';

// 从颜色生成调色板
const palette = generateAntDesign('#1677FF');
// ["#e6f4ff", "#b4d8ff", "#82baff", "#4f9bff", "#1d7dff", "#1677ff", "#0050e6", "#003aac", "#002373", "#000c39"]

// 暗色主题
const darkPalette = generateAntDesign('#1677FF', { theme: 'dark' });

Tailwind CSS 算法

生成 Tailwind CSS 风格的 11 色阶 (50-950)，主色位于 500：

import { generateTailwind } from '@builden/bd-color';

const palette = generateTailwind('#3b82f6');
// ["#eff6ff", "#dbeafe", "#bfdbfe", "#93c5fd", "#60a5fa", "#3b82f6", "#2563eb", "#1d4ed8", "#1e40af", "#1e3a8a", "#172554"]

OKLCH 平滑渐变

使用 OKLCH 色彩空间生成平滑渐变色阶：

import { generateOklch } from '@builden/bd-color';

// 默认 10 级渐变，从亮到暗
const palette = generateOklch('#3b82f6');
// 从亮度 0.95 渐变到 0.1

// 自定义配置
const customPalette = generateOklch('#3b82f6', {
  steps: 5, // 5 个色阶
  startL: 0.98, // 起始亮度
  endL: 0.15, // 结束亮度
  interpolation: 'ease-in-out', // 缓动函数
});

统一入口

使用 generate 函数统一调用：

import { generate } from '@builden/bd-color';

// 默认使用 ant-design 算法
generate('#1677FF');

// 指定算法
generate('#1677FF', { algorithm: 'ant-design' });
generate('#1677FF', { algorithm: 'tailwind' });
generate('#1677FF', { algorithm: 'oklch' });

预设颜色

Ant Design 预设

提供 13 种 Ant Design 主色及完整调色板：

import { antDesignPrimaryColors, antDesignPalettes, antDesignDarkPalettes } from '@builden/bd-color';

// 获取主色对照表
Object.keys(antDesignPrimaryColors);
// ["red", "volcano", "orange", "gold", "yellow", "lime", "green", "cyan", "blue", "geekblue", "purple", "magenta", "grey"]

// 获取蓝色调色板
const blue = antDesignPalettes.blue;
blue.primary; // "#1677ff"
blue[1]; // "#b4d8ff"
blue[5]; // "#1677ff" (主色)
blue[9]; // "#000c39"

// 暗色主题
const blueDark = antDesignDarkPalettes.blue;

Tailwind CSS 预设

提供 Tailwind CSS 风格预设：

import { tailwindPrimaryColors, tailwindPalettes } from '@builden/bd-color';

// 获取主色对照表
Object.keys(tailwindPrimaryColors);
// ["slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose"]

// 获取调色板
const blue = tailwindPalettes.blue;
blue[500]; // "#3b82f6"
blue[100]; // "#dbeafe"
blue[900]; // "#1e3a8a"

const slate = tailwindPalettes.slate;
slate[500]; // "#64748b"


## TypeScript 类型

```typescript
import type {
  ColorInput,
  RGB,
  HSL,
  HSV,
  OKLCH,
  OKLAB,
  ColorInterface,
  GenerateOptions,
  AntDesignOptions,
  TailwindOptions,
  OklchOptions,
  Palette,
  PresetColor,
  Presets,
} from '@builden/bd-color';

完整示例

React 组件中使用

import { generateTailwind, tailwindPalettes } from '@builden/bd-color';

function Button({ children, variant = 'primary' }) {
  const blue = tailwindPalettes.blue;
  const colors = generateTailwind(blue[500]);

  return (
    <button
      style={{
        backgroundColor: colors[500],
        color: '#ffffff',
        padding: '8px 16px',
        borderRadius: '6px',
        border: 'none',
      }}
    >
      {children}
    </button>
  );
}

生成主题色阶

import { generate } from '@builden/bd-color';

// 生成 Ant Design 风格色阶用于 UI 主题
const themeColors = generate('#1677FF', {
  algorithm: 'ant-design',
  theme: 'light',
});

// 生成的色阶可用于:
// themeColors[1] - 极浅背景
// themeColors[3] - 浅色背景
// themeColors[5] - 主色 (primary)
// themeColors[7] -  hover 状态
// themeColors[9] -  active 状态

许可证

MIT