# 颜色 `color` 相关方法 

> 主要包含颜色语法的转化，渐变色，颜色数据结构额度变换等相关的方法。

- [toHex](#tohex) - 将数值从 0-255 转换成 16 进制字符串
- [toRGB](#torgb) - 将颜色转换为标准的 RGB 格式（'#ffffff'）。该方法使用了缓存机制，可以提高重复颜色转换的性能。
- [arr2rgb](#arr2rgb) - 数组转换成 rgb 颜色
- [rgb2arr](#rgb2arr) - rgb 颜色转换成数组
- [gradient](#gradient) - 获取渐变函数
- [toCSSGradient](#tocssgradient) - 将 g 渐变转换为 css 渐变


## toHex

将数值从 0-255 转换成 16 进制字符串，主要用于颜色值的转换。

- 将 0-255 之间的数值转换为两位十六进制字符串
- 自动补零，确保返回两位字符串
- 对小数进行四舍五入处理
- 返回的十六进制字符串为小写形式

```ts
import { toHex } from '@antv/util';

// 基本数值转换
toHex(0);     // "00"
toHex(16);    // "10"
toHex(255);   // "ff"

// 个位数补零
toHex(1);     // "01"
toHex(9);     // "09"

// 小数四舍五入
toHex(15.4);  // "0f"
toHex(15.6);  // "10"

// 常用颜色值转换
toHex(255);   // "ff" (红/绿/蓝最大值)
toHex(128);   // "80" (中间值)
toHex(0);     // "00" (红/绿/蓝最小值)
```

- 参数说明

| 参数 | 说明 | 类型 | 默认值 |
|---------|------|------|---------|
| value | 需要转换的数值 (0-255) | number | - |

- 返回值

| 参数 | 说明 | 类型 | 默认值 |
|---------|------|------|---------|
| result | 两位十六进制字符串 | string | - |


## toRGB

将颜色转换为标准的 RGB 格式（'#ffffff'）。该方法使用了缓存机制，可以提高重复颜色转换的性能。

- 将各种格式的颜色值转换为标准的 RGB 十六进制格式（如 '#ff0000'）
- 支持颜色名称、RGB、RGBA 等格式的输入
- 使用 memoize 进行结果缓存，最多缓存 256 个结果
- 通过创建隐藏的 DOM 元素来进行颜色计算


```ts
import { toRGB } from '@antv/util';

// 颜色名称转换
toRGB('red');          // '#ff0000'
toRGB('green');        // '#008000'
toRGB('blue');         // '#0000ff'

// RGB/RGBA 格式转换
toRGB('rgb(255,0,0)');     // '#ff0000'
toRGB('rgba(0,255,0,1)');  // '#00ff00'

// 十六进制格式
toRGB('#f00');        // '#ff0000'
toRGB('#ff0000');     // '#ff0000' (保持不变)

// 其他颜色名称
toRGB('lightblue');   // '#add8e6'
toRGB('skyblue');     // '#87ceeb'
toRGB('darkred');     // '#8b0000'
```

- 参数说明

| 参数 | 说明 | 类型 | 默认值 |
|---------|------|------|--------- |
| color | 输入的颜色值 | string | - |

- 返回值

| 参数 | 说明 | 类型 | 默认值 |
|---------|------|------|---------|
| rgb | 标准的 RGB 十六进制颜色字符串 | string | - |


## arr2rgb

将 RGB 数组转换成十六进制颜色字符串。

- 将包含三个数值（红、绿、蓝）的数组转换为十六进制颜色字符串
- 每个数值范围应在 0-255 之间
- 返回格式为 "#RRGGBB" 的颜色字符串
- 使用 toHex 函数处理每个颜色分量

```ts
import { arr2rgb } from '@antv/util';

// 基本颜色转换
arr2rgb([255, 0, 0]);      // "#ff0000" (红色)
arr2rgb([0, 255, 0]);      // "#00ff00" (绿色)
arr2rgb([0, 0, 255]);      // "#0000ff" (蓝色)

// 混合颜色
arr2rgb([255, 255, 0]);    // "#ffff00" (黄色)
arr2rgb([255, 0, 255]);    // "#ff00ff" (紫色)
arr2rgb([0, 255, 255]);    // "#00ffff" (青色)

// 灰度值
arr2rgb([128, 128, 128]);  // "#808080" (灰色)
arr2rgb([0, 0, 0]);        // "#000000" (黑色)
arr2rgb([255, 255, 255]);  // "#ffffff" (白色)

// 带小数的值（会被四舍五入）
arr2rgb([128.6, 128.4, 128.5]);  // "#808080"
```

- 参数说明

| 参数 | 说明 | 类型 | 默认值 |
|---------|------|------|---------|
| arr | RGB 颜色值数组 | number[] | - |

- 返回值

| 参数 | 说明 | 类型 | 默认值 |
|---------|------|------|---------|
| result | 十六进制颜色字符串 | string | - |

## rgb2arr

将十六进制颜色字符串转换为 RGB 数组。

- 将 "#RRGGBB" 格式的颜色字符串转换为 [R, G, B] 数组
- 每个返回值都是 0-255 之间的整数
- 支持解析标准的六位十六进制颜色值
- 返回一个包含三个数值的数组，分别表示红、绿、蓝

```ts
import { rgb2arr } from '@antv/util';

// 基本颜色转换
rgb2arr('#ff0000');  // [255, 0, 0] (红色)
rgb2arr('#00ff00');  // [0, 255, 0] (绿色)
rgb2arr('#0000ff');  // [0, 0, 255] (蓝色)

// 混合颜色
rgb2arr('#ffff00');  // [255, 255, 0] (黄色)
rgb2arr('#ff00ff');  // [255, 0, 255] (紫色)
rgb2arr('#00ffff');  // [0, 255, 255] (青色)

// 灰度值
rgb2arr('#808080');  // [128, 128, 128] (灰色)
rgb2arr('#000000');  // [0, 0, 0] (黑色)
rgb2arr('#ffffff');  // [255, 255, 255] (白色)

// 其他值
rgb2arr('#a1b2c3');  // [161, 178, 195]
```

- 参数说明

| 参数 | 说明 | 类型 | 默认值 |
|---------|------|------|---------|
| str | 十六进制颜色字符串 | string | - |

- 返回值

| 参数 | 说明 | 类型 | 默认值 |
|---------|------|------|---------|
| rgbs | RGB 颜色值数组 | number[] | - |


## gradient

获取颜色渐变函数，用于计算多个颜色之间的过渡值。

- 接受多个颜色值，创建一个渐变函数
- 支持字符串（用'-'分隔）或数组形式的颜色输入
- 支持颜色名称、十六进制等多种颜色格式
- 返回一个函数，通过百分比获取渐变颜色

```ts
import { gradient } from '@antv/util';

// 双色渐变
const redToBlue = gradient(['#ff0000', '#0000ff']);
redToBlue(0);    // "#ff0000" (红色)
redToBlue(0.5);  // "#800080" (紫色)
redToBlue(1);    // "#0000ff" (蓝色)

// 多色渐变
const rainbow = gradient(['#ff0000', '#ffff00', '#00ff00', '#0000ff']);
rainbow(0);      // "#ff0000" (红色)
rainbow(0.33);   // 接近黄色
rainbow(0.66);   // 接近绿色
rainbow(1);      // "#0000ff" (蓝色)

// 使用颜色名称
const gradient1 = gradient('red-yellow-green');
gradient1(0);    // "#ff0000"
gradient1(0.5);  // 黄色和绿色的中间色
gradient1(1);    // "#008000"

// 混合使用颜色名称和十六进制
const gradient2 = gradient(['red', '#00ff00', 'blue']);
gradient2(0.5);  // 绿色和蓝色的中间色
```

- 参数说明

| 参数 | 说明 | 类型 | 默认值 |
|---------|------|------|---------|
| colors | 颜色值列表 | string \| string[] | - |

- 返回值

| 参数 | 说明 | 类型 | 默认值 |
|---------|------|------|---------|
| gradientFunction | 渐变函数 | (percent: number) => string | - |

- 注意事项

1. 输入颜色可以是颜色名称或十六进制格式
2. 百分比参数范围应在 0-1 之间
3. 超出范围的百分比会被限制在 0-1 之间
4. 非数字的百分比会被转换为 0
5. 渐变计算是线性的
6. 返回的颜色始终是十六进制格式

## toCSSGradient

将 G 渐变格式转换为标准的 CSS 渐变格式。

- 支持线性渐变（l）和径向渐变（r）的转换
- 自动调整渐变角度（CSS 和 G 的渐变起始角度差 90 度）
- 将色标位置从 0-1 转换为百分比
- 保持非渐变颜色值不变

```ts
import { toCSSGradient } from '@antv/util';

// 线性渐变
const linear1 = 'l(0) 0:#ffffff 1:#000000';
toCSSGradient(linear1);  
// "linear-gradient(90deg, #ffffff 0%, #000000 100%)"

const linear2 = 'l(90) 0:#ff0000 0.5:#00ff00 1:#0000ff';
toCSSGradient(linear2);  
// "linear-gradient(180deg, #ff0000 0%, #00ff00 50%, #0000ff 100%)"

// 带空格的格式
const linear3 = 'l  (45)  0: #fff   1: #000';
toCSSGradient(linear3);  
// "linear-gradient(135deg, #fff 0%, #000 100%)"

// 径向渐变
const radial1 = 'r(0.5, 0.5, 0.5) 0:#ffffff 1:#000000';
toCSSGradient(radial1);  
// "radial-gradient(#ffffff 0%, #000000 100%)"

// 多色停止点的径向渐变
const radial2 = 'r(0.5, 0.5, 0.5) 0:#ff0000 0.5:#00ff00 1:#0000ff';
toCSSGradient(radial2);  
// "radial-gradient(#ff0000 0%, #00ff00 50%, #0000ff 100%)"

// 非渐变颜色
toCSSGradient('#ff0000');  // "#ff0000"
```

- 参数说明

| 参数 | 说明 | 类型 | 默认值 |
|---------|------|------|---------|
| gradientColor | G 渐变格式的颜色字符串 | string | - |

- 返回值

| 参数 | 说明 | 类型 | 默认值 |
|---------|------|------|---------|
| result | CSS 渐变字符串 | string | - |

- 注意事项

1. 线性渐变格式：`l(angle) position:color ...`
2. 径向渐变格式：`r(x, y, r) position:color ...`
3. 位置值范围是 0-1，会被转换为百分比
4. 支持多个色标点
5. 自动处理空格
6. 非渐变颜色会原样返回