mix

将两个或多个颜色混合，通过平均计算它们的 R、G、B 和透明度通道来创建一个新的十六进制颜色值。

示例

基本用法

import { mix } from '@esdora/color'

// 混合红色和蓝色得到紫色
mix('#ff0000', '#0000ff') // => '#800080'

// 混合红、绿、蓝得到中性灰
mix('#ff0000', '#00ff00', '#0000ff') // => '#555555'

// 混合红、绿、蓝、黄得到偏黄的中性色
mix('#ff0000', '#00ff00', '#0000ff', '#ffff00') // => '#808040'

混合带透明度的颜色

import { mix } from '@esdora/color'

// 透明度通道也会被平均计算
mix('rgba(255, 0, 0, 0.8)', 'rgba(0, 255, 0, 0.4)') // => '#80800099'

// 多个带透明度的颜色
mix(
  'rgba(255, 0, 0, 1)',
  'rgba(0, 255, 0, 0.5)',
  'rgba(0, 0, 255, 0)',
) // => '#55555580'

创建渐变中间色与调色板

import { mix } from '@esdora/color'

// 红色和绿色混合得到黄色系中间色
mix('#ff0000', '#00ff00') // => '#808000'

// 绿色和蓝色混合得到青色系中间色
mix('#00ff00', '#0000ff') // => '#008080'

// 白色和黑色混合得到中性灰，可作为调色板中的中间色
mix('#ffffff', '#000000') // => '#808080'

签名与说明

类型签名

import type { EsdoraColor } from '@esdora/color'

/**
 * 混合多个颜色，创建一个新的颜色。
 *
 * 此函数可以混合任意数量的颜色，通过在 RGB 色彩空间中进行平均计算。
 * 每个颜色的权重相等。
 */
export function mix(...colors: (string | EsdoraColor)[]): string | null

参数说明

参数	类型	描述	必需
colors	(string | EsdoraColor)	要混合的颜色参数列表，至少需要 1 个，可以是颜色字符串或符合 Culori 规范的 EsdoraColor。	是

mix 使用剩余参数形式：可以传入任意数量的颜色，例如 mix(color1, color2) 或 mix(...colorsArray)。

返回值

• 类型: string | null
• 说明:
  • 当至少提供一个有效颜色并成功完成混合时，返回混合后的十六进制颜色字符串。
  • 当所有输入颜色透明度的平均值小于 1 时，返回 8 位十六进制字符串（#rrggbbaa）；否则返回 6 位十六进制字符串（#rrggbb）。
• 特殊情况:
  • 当 colors 为空（即未提供任何参数）时，会抛出 TypeError，提示“至少需要提供一个颜色”。
  • 当只提供一个颜色时，函数会直接返回该颜色对应的标准化十六进制格式（含透明度判断）。
  • 当任一颜色无法解析或在转换为 RGB 过程中发生错误时，函数返回 null。

泛型约束（如适用）

本函数不使用泛型类型参数。

注意事项与边界情况

输入边界

• 必须至少提供一个颜色；否则会抛出 TypeError('至少需要提供一个颜色')。
• 当只提供一个颜色时，mix 退化为格式标准化工具：
  • 例如 mix('#ff0000') 返回 '#ff0000'。
  • 对带透明度的单个颜色，返回 8 位十六进制字符串（例如 mix('rgba(255, 0, 0, 0.5)') 返回匹配 ^#[0-9a-f]{8}$ 的值）。
• 支持多种输入格式：短/长 HEX、rgb(...)、hsl(...)、rgba(...)、颜色名称以及 culori 风格的颜色对象。

错误处理

• 当 colors 为空时，立即抛出 TypeError 异常；调用方可按需使用 try/catch 包裹：

  import { mix } from '@esdora/color'
  
  try {
    mix()
  }
  catch (error) {
    // 处理“至少需要提供一个颜色”的错误
  }

• 当任一颜色解析失败（例如传入 'invalid-color'、null 或无法解析的对象）时，函数返回 null：

  • mix('invalid-color') // => null
  • mix('#ff0000', 'invalid-color') // => null

• 当颜色对象模式与 RGB 转换不兼容时（例如 mode: 'invalid'），内部的 rgb 转换会抛出异常，mix 使用 try/catch 捕获并返回 null，避免异常向外传播。

• 调用方通常只需对返回值是否为 null 做一次检查，只有在“完全不传参数”时需要考虑捕获异常。

性能考虑

• 时间复杂度: O(n) —— 需要对传入的每个颜色进行解析、转换和通道累加，其中 n 为颜色数量。
• 空间复杂度: O(n) —— 内部为每个颜色创建一个中间 RGB 表示对象。
• 优化建议:
  • 适合用于构建调色板、生成渐变中间色、合成中性色等场景；在颜色数量较少（几十个以内）时性能开销可忽略。
  • 若需要对大量颜色组合进行重复混合，建议在业务层对固定组合的结果做缓存。

相关链接

• 源码