convertColor

将颜色在不同格式间转换（hex、rgb、rgba、hsl、hsla、named）。

函数签名

function convertColor(
  input: string | RgbColor | HslColor | number[],
  targetFormat: ColorFormat,
  options?: {
    includeAlpha?: boolean
    precision?: number
  }
): string | null

type ColorFormat = 'hex' | 'rgb' | 'rgba' | 'hsl' | 'hsla' | 'named'

interface RgbColor {
  r: number  // 0-255
  g: number  // 0-255
  b: number  // 0-255
  a?: number // 0-1
}

interface HslColor {
  h: number  // 0-360
  s: number  // 0-100
  l: number  // 0-100
  a?: number // 0-1
}

参数

参数名	类型	必填	默认值	说明
input	string | RgbColor | HslColor | number[]	是	-	输入颜色，支持字符串、对象、数组
targetFormat	ColorFormat	是	-	目标格式
options	Object	否	{}	转换选项
options.includeAlpha	boolean	否	false	是否包含 alpha 通道
options.precision	number	否	0	数值精度（0-10）

返回值

类型	说明
string | null	转换后的颜色字符串，失败返回 null

异常

错误类型	说明
ColorConversionError	颜色转换失败（被捕获，返回 null）

工作原理

1. 输入验证：

   • 检查目标格式是否有效
   • 检查选项参数是否合法

2. 输入标准化：

   • 字符串：解析为 RGB/RGBA
   • 对象：提取 RGB 或 HSL 值
   • 数组：解析为 RGB/RGBA
   • 命名颜色：转换为 RGB

3. 格式转换：

   • RGB ↔ HSL：使用色彩空间转换算法
   • 十六进制：RGB 值转换为 16 进制
   • Alpha 通道：根据选项保留或丢弃

4. 输出格式化：

   • 根据 targetFormat 格式化字符串
   • 根据 precision 控制小数位数
   • 根据 includeAlpha 决定是否包含 alpha

5. 错误处理：

   • 捕获所有子函数抛出的错误
   • 使用 JSON.stringify 生成详细错误消息（JavaScript 标准内置对象）
   • 返回 null 表示转换失败

支持的输入格式：

• 十六进制：#RGB, #RRGGBB, #RRGGBBAA
• RGB/RGBA：rgb(r, g, b), rgba(r, g, b, a)
• HSL/HSLA：hsl(h, s%, l%), hsla(h, s%, l%, a)
• 命名颜色：red, blue, green 等
• 对象：{ r, g, b, a? }, { h, s, l, a? }
• 数组：[r, g, b], [r, g, b, a]