✨ 特性

• 🪶 极小体积 — 核心约 4KB（gzip），零依赖
• 🔌 插件系统 — 类似 dayjs 的扩展机制，按需加载
• 🎯 TypeScript 优先 — 完整的类型定义和智能提示
• ⛓️ 链式 API — 所有操作支持流畅的链式调用
• 🎨 多格式支持 — Hex、RGB、HSL、HSV、CSS 颜色名、数字
• 🏷️ 方法别名 — 简写别名如 r()、g()、b()、h()、s()、l()
• ♿ 无障碍 — WCAG 对比度、可读性检查（通过插件）
• 🎭 混合模式 — 类似 Photoshop 的颜色混合（通过插件）
• 🧪 测试完善 — 接近 100% 的测试覆盖率

📦 安装

npm install @xpyjs/color

yarn add @xpyjs/color

pnpm add @xpyjs/color

环境要求： Node.js >= 14.0.0 | 浏览器：ES2015+（ES6）

🚀 快速开始

import xcolor from '@xpyjs/color'

// 从多种格式创建
const red = xcolor('#ff0000')
const blue = xcolor('rgb(0, 0, 255)')
const green = xcolor('hsl(120, 100%, 50%)')
const named = xcolor('coral')
const obj = xcolor({ r: 255, g: 128, b: 0 })
const num = xcolor(0xFF8040)

// 链式操作
const result = xcolor('#ff0000')
  .lighten(20)
  .saturate(10)
  .alpha(0.8)
  .toHex()

// 查询属性
xcolor('#fff').isLight() // true
xcolor('#000').isDark()  // true

// 颜色对比
xcolor('#000').contrast('#fff') // 21（最大对比度）

📖 API 参考

创建颜色

import xcolor from '@xpyjs/color'

// 工厂函数（推荐）
xcolor('#ff0000')              // Hex
xcolor('#f00')                 // 简写 Hex
xcolor('#ff000080')            // 带透明度的 Hex
xcolor('rgb(255, 0, 0)')      // RGB 字符串
xcolor('rgba(255, 0, 0, 0.5)')// RGBA 字符串
xcolor('rgb(255 0 0 / 0.5)')  // 现代 CSS 语法
xcolor('hsl(0, 100%, 50%)')   // HSL 字符串
xcolor('hsla(0, 100%, 50%, 0.5)') // HSLA 字符串
xcolor('hsv(0, 100%, 100%)')  // HSV 字符串
xcolor('red')                  // CSS 颜色名（148种）
xcolor({ r: 255, g: 0, b: 0 })// 对象
xcolor(0xFF0000)               // 数字
xcolor()                       // 默认黑色

// 静态方法
xcolor.random()                // 随机颜色
xcolor.isColor(value)          // 类型守卫

通道访问（获取/设置）

所有通道方法都支持双重用法：无参调用为获取，传参为设置（可链式调用）。

const c = xcolor('#ff8040')

// 获取通道值
c.red()        // 255        （别名：c.r()）
c.green()      // 128        （别名：c.g()）
c.blue()       // 64         （别名：c.b()）
c.alpha()      // 1          （别名：c.opacity()）

// 设置通道值（支持链式调用）
c.red(200).green(100).blue(50).alpha(0.8)
// 或使用别名：
c.r(200).g(100).b(50).opacity(0.8)

// HSL 通道访问
c.hue()         // 获取色相 (0-360)        （别名：c.h()）
c.hue(180)      // 设置色相                 （别名：c.h(180)）
c.saturation()  // 获取饱和度 (0-100)       （别名：c.s()）
c.lightness()   // 获取/设置亮度 (0-100)    （别名：c.l()）

输出方法

const c = xcolor('#ff8040')

c.toHex()            // '#ff8040'
c.toHex(true)        // '#ff8040'（若可能则输出 #RGB）
c.toHex(false, true) // '#ff8040ff'（强制包含透明度）
c.toHexString()      // toHex() 的别名
c.toRgb()            // { r: 255, g: 128, b: 64, a: 1 }
c.toRgbString()      // 'rgb(255, 128, 64)'
c.toRgbArray()       // [255, 128, 64, 1]
c.toHsl()            // { h: 20, s: 100, l: 62.55, a: 1 }
c.toHslString()      // 'hsl(20, 100%, 63%)'
c.toHsv()            // { h: 20, s: 74.9, v: 100, a: 1 }
c.toHsvString()      // 'hsv(20, 75%, 100%)'
c.toNumber()         // 16744512 (0xFF8040)
c.toPercentageRgb()  // { r: '100%', g: '50%', b: '25%', a: 1 }
c.toName()           // 精确匹配返回 CSS 颜色名，否则 undefined
c.toObject()         // toRgb() 的别名
c.toString()         // 自动选择最佳格式
c.toString('hex')    // 强制格式：'hex' | 'hex3' | 'hex8' | 'rgb' | 'hsl' | 'hsv' | 'name'
                     // 插件可扩展：'cmyk' | 'percentageRgb'

颜色操作

所有操作方法会修改实例并返回 this，支持链式调用。

const c = xcolor('#ff0000')

// 亮度
c.lighten(20)     // HSL 亮度增加 20
c.darken(20)      // HSL 亮度降低 20
c.brighten(20)    // 加性增亮（趋向白色）

// 饱和度
c.saturate(20)    // 饱和度增加 20
c.desaturate(20)  // 饱和度降低 20
c.grayscale()     // 完全去饱和（别名：greyscale）

// 色相
c.spin(120)       // 色相旋转 120°
c.rotate(120)     // spin 的别名

// 反转
c.negate()        // 反转颜色 (255 - 通道值）
c.invert()        // negate 的别名

// 透明度
c.fade(20)        // 透明度降低 20%（别名：fadeOut）
c.opaquer(20)     // 透明度增加 20%（别名：fadeIn）

// 混合
c.tint(50)        // 与白色混合 50%
c.shade(50)       // 与黑色混合 50%
c.mix('#0000ff', 50) // 与蓝色混合 50%

查询方法

const c = xcolor('#ff0000')

c.isLight()           // false
c.isDark()            // true
c.isValid()           // true
c.brightness()        // 76.245（YIQ 亮度，0-255）
c.luminance()         // 0.2126（WCAG 相对亮度）
c.contrast('#ffffff') // 3.99（WCAG 对比度，1-21）
c.equals('#ff0000')   // true
c.clone()             // 创建独立副本

方法别名一览

| 完整名称 | 别名 | 说明 | | ---------------- | -------------------- | ------------------ | | red() | r() | 红色通道（获取/设置）| | green() | g() | 绿色通道（获取/设置）| | blue() | b() | 蓝色通道（获取/设置）| | alpha() | a()、opacity() | 透明度（获取/设置）| | hue() | h() | 色相（获取/设置） | | saturation() | s() | 饱和度（获取/设置）| | lightness() | l() | 亮度（获取/设置） | | value() | v() | HSV 明度（获取/设置）| | grayscale() | greyscale() | 完全去饱和 | | spin() | rotate() | 旋转色相 | | negate() | invert() | 反转颜色 | | fade() | fadeOut() | 降低透明度 | | opaquer() | fadeIn() | 增加透明度 | | toHex() | toHexString() | Hex 输出 | | toRgb() | toObject() | RGBA 对象输出 |

🔌 插件

通过插件扩展功能，灵感来自 dayjs 的架构设计。

使用插件

import xcolor from '@xpyjs/color'
import harmony from '@xpyjs/color/plugins/harmony'
import a11y from '@xpyjs/color/plugins/a11y'

// 注册插件（可链式调用）
xcolor.use(harmony).use(a11y)

// 使用新方法
xcolor('#ff0000').complement()
xcolor('#000').isReadable('#fff')

可用插件

🎵 Harmony — 色彩和谐组合

import harmony from '@xpyjs/color/plugins/harmony'
xcolor.use(harmony)

xcolor('#ff0000').complement()      // 互补色（180°）
xcolor('#ff0000').triad()           // 三色组，间隔 120°
xcolor('#ff0000').tetrad()          // 四色组，间隔 90°
xcolor('#ff0000').splitComplement() // 分裂互补色
xcolor('#ff0000').analogous(6, 30)  // 类似色
xcolor('#ff0000').monochromatic(6)  // 单色系变化

♿ A11y — 无障碍工具

import a11y from '@xpyjs/color/plugins/a11y'
xcolor.use(a11y)

xcolor('#000').isReadable('#fff')                     // true
xcolor('#000').isReadable('#fff', { level: 'AAA' })   // true
xcolor('#fff').mostReadable(['#000', '#888', '#fff']) // 返回黑色
xcolor('#000').wcagLevel('#fff')
// { level: 'AAA', largeText: 'AAA', ratio: 21 }

🎭 Blend — 颜色混合模式

import blend from '@xpyjs/color/plugins/blend'
xcolor.use(blend)

xcolor('#ff0000').blend('#0000ff', 'multiply')
xcolor('#ff0000').blend('#0000ff', 'screen')
// 还支持： overlay, darken, lighten, dodge, burn, hardLight, softLight, difference, exclusion

🌈 Gradient — 颜色渐变和色板

import gradient from '@xpyjs/color/plugins/gradient'
xcolor.use(gradient)

xcolor('#ff0000').gradient('#0000ff', 5) // 5 步渐变数组
xcolor('#ff0000').tones(5)               // 暗色 + 原色 + 亮色

🖨️ CMYK — CMYK 色彩空间

import cmyk from '@xpyjs/color/plugins/cmyk'
xcolor.use(cmyk)

xcolor('#ff0000').toCmyk()       // { c: 0, m: 100, y: 100, k: 0 }
xcolor('#ff0000').toCmykString() // 'cmyk(0%, 100%, 100%, 0%)'
xcolor('#ff0000').toString('cmyk') // 'cmyk(0%, 100%, 100%, 0%)'

🔬 Lab — CIE Lab 色彩空间和色差

import lab from '@xpyjs/color/plugins/lab'
xcolor.use(lab)

xcolor('#ff0000').toLab()           // { l: 53.23, a: 80.11, b: 67.22 }
xcolor('#ff0000').toLabString()     // 'lab(53.23% 80.11 67.22)'
xcolor('#ff0000').deltaE('#fe0000') // 色差（(0-100+)

🏷️ Name — 最接近颜色名称查找

import name from '@xpyjs/color/plugins/name'
xcolor.use(name)

xcolor('#fe0000').closestName()  // 'red'
xcolor('#f1f2f3').closestName()  // 最接近的 CSS 颜色名
xcolor('red')                    // 创建 #ff0000 对应的颜色实例
xcolor('CornflowerBlue')         // 创建 #6495ed 对应的颜色实例

📊 PercentageRgb — 百分比 RGB 输出

import percentageRgb from '@xpyjs/color/plugins/percentageRgb'
xcolor.use(percentageRgb)

xcolor('#ff8000').toPercentageRgb() // { r: '100%', g: '50%', b: '0%', a: 1 }
xcolor('#ff8000').toString('percentageRgb') // 'rgba(100%, 50%, 0%, 1)'

📚 提供 20+ 个插件。 查看完整插件文档了解所有可用插件，包括 HWB、OKLab、XYZ、Display P3、Rec2020、Scale、Simulate、Temperature、Theme、Palette 等。

创建新插件

使用脚手架脚本快速创建插件：

npm run create:plugin myPlugin

会自动创建：

• src/plugins/myPlugin/index.ts — 包含模板的插件源码
• test/plugins/myPlugin.test.ts — 包含模板的测试文件

插件会被构建系统自动检测并打包。

手动创建插件

import xcolor, { type XColorPlugin } from '@xpyjs/color'

declare module '@xpyjs/color' {
  interface XColor {
    myMethod(): string
  }
}

const myPlugin: XColorPlugin = {
  name: '@xpyjs/color/plugins/my-plugin',
  install(_option, cls, _factory) {
    const proto: any = cls.prototype
    proto.myMethod = function () {
      return `颜色: ${this.toHex()}`
    }
  }
}

xcolor.use(myPlugin)

插件通过 name 注册。如果同名插件再次注册，旧的注册将被覆盖并输出警告。

如果插件需要 clamp、round 或 parser 工具等能力，请直接从 @xpyjs/color 导入，不要依赖额外的 utils 参数。

🔧 工具函数导出

高级用法可以直接导入工具函数：

import {
  clamp, round,
  rgbToHsl, hslToRgb,
  rgbToHsv, hsvToRgb,
  relativeLuminance, contrastRatio
} from '@xpyjs/color'

🌐 浏览器使用

CDN (UMD)

<script src="https://unpkg.com/@xpyjs/color/dist/index.umd.js"></script>
<script>
  const c = xcolor('#ff0000')
  console.log(c.toHsl())
</script>

ES Module

<script type="module">
  import xcolor from 'https://unpkg.com/@xpyjs/color/dist/index.esm.js'
  const c = xcolor('#ff0000')
  console.log(c.toHsl())
</script>

📄 许可证

MIT © xpyjs