> ## Documentation Index
> Fetch the complete documentation index at: https://bun.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 颜色

> 将颜色格式化为 CSS、ANSI、数字、十六进制字符串等多种格式

`Bun.color(input, outputFormat?)` 利用 Bun 的 CSS 解析器来解析、规范化并转换用户输入的颜色，支持多种输出格式，包括：

| 格式           | 示例                               |
| ------------ | -------------------------------- |
| `"css"`      | `"red"`                          |
| `"ansi"`     | `"\x1b[38;2;255;0;0m"`           |
| `"ansi-16"`  | `"\x1b[38;5;\tm"`                |
| `"ansi-256"` | `"\x1b[38;5;196m"`               |
| `"ansi-16m"` | `"\x1b[38;2;255;0;0m"`           |
| `"number"`   | `0x1a2b3c`                       |
| `"rgb"`      | `"rgb(255, 99, 71)"`             |
| `"rgba"`     | `"rgba(255, 99, 71, 0.5)"`       |
| `"hsl"`      | `"hsl(120, 50%, 50%)"`           |
| `"hex"`      | `"#1a2b3c"`                      |
| `"HEX"`      | `"#1A2B3C"`                      |
| `"{rgb}"`    | `{ r: 255, g: 99, b: 71 }`       |
| `"{rgba}"`   | `{ r: 255, g: 99, b: 71, a: 1 }` |
| `"[rgb]"`    | `[ 255, 99, 71 ]`                |
| `"[rgba]"`   | `[ 255, 99, 71, 255]`            |

有许多不同的方式可以使用此 API：

* 验证并规范化颜色，以便将其持久化到数据库中（`number` 是最适合数据库的）
* 将颜色转换为不同格式
* 除了许多今天正在使用的那 16 种颜色之外进行更丰富的彩色日志（使用 `ansi` 自动检测终端的颜色支持，或使用 `ansi-16`、`ansi-256`、`ansi-16m` 来指定目标颜色深度）
* 为在 HTML 中注入的 CSS 格式化颜色
* 从 CSS 颜色字符串中获取 `r`、`g`、`b` 和 `a` 颜色组件，作为 JavaScript 对象或数字

你可以将其视为流行 npm 包 [`color`](https://github.com/Qix-/color) 和 [`tinycolor2`](https://github.com/bgrins/TinyColor) 的替代品，不过它内置 Bun，支持完整解析 CSS 颜色字符串且没有任何依赖。

### 灵活的输入

你可以传入以下任意一种：

* 标准 CSS 颜色名称，如 `"red"`
* 数字，如 `0xff0000`
* 十六进制字符串，如 `"#f00"`
* RGB 字符串，如 `"rgb(255, 0, 0)"`
* RGBA 字符串，如 `"rgba(255, 0, 0, 1)"`
* HSL 字符串，如 `"hsl(0, 100%, 50%)"`
* HSLA 字符串，如 `"hsla(0, 100%, 50%, 1)"`
* RGB 对象，如 `{ r: 255, g: 0, b: 0 }`
* RGBA 对象，如 `{ r: 255, g: 0, b: 0, a: 1 }`
* RGB 数组，如 `[255, 0, 0]`
* RGBA 数组，如 `[255, 0, 0, 255]`
* LAB 字符串，如 `"lab(50% 50% 50%)"`
* ……任何 CSS 能解析成单个颜色值的内容

### 将颜色格式化为 CSS

`"css"` 格式输出的是有效的 CSS，用于样式表、内联样式、CSS 变量、css-in-js 等，返回颜色的最紧凑字符串表示。

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
Bun.color("red", "css"); // "red"
Bun.color(0xff0000, "css"); // "#f000"
Bun.color("#f00", "css"); // "red"
Bun.color("#ff0000", "css"); // "red"
Bun.color("rgb(255, 0, 0)", "css"); // "red"
Bun.color("rgba(255, 0, 0, 1)", "css"); // "red"
Bun.color("hsl(0, 100%, 50%)", "css"); // "red"
Bun.color("hsla(0, 100%, 50%, 1)", "css"); // "red"
Bun.color({ r: 255, g: 0, b: 0 }, "css"); // "red"
Bun.color({ r: 255, g: 0, b: 0, a: 1 }, "css"); // "red"
Bun.color([255, 0, 0], "css"); // "red"
Bun.color([255, 0, 0, 255], "css"); // "red"
```

如果输入未知或解析失败，`Bun.color` 返回 `null`。

### 将颜色格式化为 ANSI（用于终端）

`"ansi"` 格式输出适用于终端的 ANSI 转义码，实现彩色文本。

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
Bun.color("red", "ansi"); // "\u001b[38;2;255;0;0m"
Bun.color(0xff0000, "ansi"); // "\u001b[38;2;255;0;0m"
Bun.color("#f00", "ansi"); // "\u001b[38;2;255;0;0m"
Bun.color("#ff0000", "ansi"); // "\u001b[38;2;255;0;0m"
Bun.color("rgb(255, 0, 0)", "ansi"); // "\u001b[38;2;255;0;0m"
Bun.color("rgba(255, 0, 0, 1)", "ansi"); // "\u001b[38;2;255;0;0m"
Bun.color("hsl(0, 100%, 50%)", "ansi"); // "\u001b[38;2;255;0;0m"
Bun.color("hsla(0, 100%, 50%, 1)", "ansi"); // "\u001b[38;2;255;0;0m"
Bun.color({ r: 255, g: 0, b: 0 }, "ansi"); // "\u001b[38;2;255;0;0m"
Bun.color({ r: 255, g: 0, b: 0, a: 1 }, "ansi"); // "\u001b[38;2;255;0;0m"
Bun.color([255, 0, 0], "ansi"); // "\u001b[38;2;255;0;0m"
Bun.color([255, 0, 0, 255], "ansi"); // "\u001b[38;2;255;0;0m"
```

它会根据 stdout 的色深自动选择 `"ansi-16m"`、`"ansi-256"` 或 `"ansi-16"`，取决于环境变量。如果 stdout 不支持任何形式的 ANSI 颜色，则返回空字符串。与 Bun 其他颜色 API 一样，如果输入未知或解析失败，返回 `null`。

#### 24 位 ANSI 颜色 (`ansi-16m`)

`"ansi-16m"` 格式输出24位 ANSI 颜色，用于可显示 1600 万色的现代终端。

它会将输入颜色转换为 RGBA，然后输出 ANSI 颜色。

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
Bun.color("red", "ansi-16m"); // "\x1b[38;2;255;0;0m"
Bun.color(0xff0000, "ansi-16m"); // "\x1b[38;2;255;0;0m"
Bun.color("#f00", "ansi-16m"); // "\x1b[38;2;255;0;0m"
Bun.color("#ff0000", "ansi-16m"); // "\x1b[38;2;255;0;0m"
```

#### 256 色 ANSI (`ansi-256`)

`"ansi-256"` 格式，将输入颜色近似到终端支持的 256 色之一。

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
Bun.color("red", "ansi-256"); // "\u001b[38;5;196m"
Bun.color(0xff0000, "ansi-256"); // "\u001b[38;5;196m"
Bun.color("#f00", "ansi-256"); // "\u001b[38;5;196m"
Bun.color("#ff0000", "ansi-256"); // "\u001b[38;5;196m"
```

RGBA 转换为256色的算法来源于 [`tmux`](https://github.com/tmux/tmux/blob/dae2868d1227b95fd076fb4a5efa6256c7245943/colour.c#L44-L55)。

#### 16 色 ANSI (`ansi-16`)

`"ansi-16"` 格式，将输入颜色近似到大多数终端支持的16色之一。

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
Bun.color("red", "ansi-16"); // "\u001b[38;5;\tm"
Bun.color(0xff0000, "ansi-16"); // "\u001b[38;5;\tm"
Bun.color("#f00", "ansi-16"); // "\u001b[38;5;\tm"
Bun.color("#ff0000", "ansi-16"); // "\u001b[38;5;\tm"
```

它首先将输入转换为24位 RGB 色彩空间，再转换为 `ansi-256`，然后再转换为最近的16色。

### 将颜色格式化为数字

`"number"` 格式输出一个24位数字，用于数据库、配置或任何需要紧凑表示颜色的场景。

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
Bun.color("red", "number"); // 16711680
Bun.color(0xff0000, "number"); // 16711680
Bun.color({ r: 255, g: 0, b: 0 }, "number"); // 16711680
Bun.color([255, 0, 0], "number"); // 16711680
Bun.color("rgb(255, 0, 0)", "number"); // 16711680
Bun.color("rgba(255, 0, 0, 1)", "number"); // 16711680
Bun.color("hsl(0, 100%, 50%)", "number"); // 16711680
Bun.color("hsla(0, 100%, 50%, 1)", "number"); // 16711680
```

### 获取红、绿、蓝和 alpha 通道

你可以使用 `"{rgba}"`、`"{rgb}"`、`"[rgba]"` 和 `"[rgb]"` 格式获取红绿蓝和 alpha 通道，分别以对象或数组形式。

#### `{rgba}` 对象

`"{rgba}"` 格式输出包含红、绿、蓝和 alpha 通道的对象。

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
type RGBAObject = {
  // 0 - 255
  r: number;
  // 0 - 255
  g: number;
  // 0 - 255
  b: number;
  // 0 - 1
  a: number;
};
```

示例：

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
Bun.color("hsl(0, 0%, 50%)", "{rgba}"); // { r: 128, g: 128, b: 128, a: 1 }
Bun.color("red", "{rgba}"); // { r: 255, g: 0, b: 0, a: 1 }
Bun.color(0xff0000, "{rgba}"); // { r: 255, g: 0, b: 0, a: 1 }
Bun.color({ r: 255, g: 0, b: 0 }, "{rgba}"); // { r: 255, g: 0, b: 0, a: 1 }
Bun.color([255, 0, 0], "{rgba}"); // { r: 255, g: 0, b: 0, a: 1 }
```

为了与 CSS 保持一致，`a` 通道是 0 到 1 之间的小数。

`"{rgb}"` 格式类似，但不包含 alpha 通道。

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
Bun.color("hsl(0, 0%, 50%)", "{rgb}"); // { r: 128, g: 128, b: 128 }
Bun.color("red", "{rgb}"); // { r: 255, g: 0, b: 0 }
Bun.color(0xff0000, "{rgb}"); // { r: 255, g: 0, b: 0 }
Bun.color({ r: 255, g: 0, b: 0 }, "{rgb}"); // { r: 255, g: 0, b: 0 }
Bun.color([255, 0, 0], "{rgb}"); // { r: 255, g: 0, b: 0 }
```

#### `[rgba]` 数组

`"[rgba]"` 格式输出包含红、绿、蓝和 alpha 通道的数组。

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
// 所有值范围 0 - 255
type RGBAArray = [number, number, number, number];
```

示例：

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
Bun.color("hsl(0, 0%, 50%)", "[rgba]"); // [128, 128, 128, 255]
Bun.color("red", "[rgba]"); // [255, 0, 0, 255]
Bun.color(0xff0000, "[rgba]"); // [255, 0, 0, 255]
Bun.color({ r: 255, g: 0, b: 0 }, "[rgba]"); // [255, 0, 0, 255]
Bun.color([255, 0, 0], "[rgba]"); // [255, 0, 0, 255]
```

与 `"{rgba}"` 格式不同，alpha 通道是 0 到 255 的整数。这适用于每个通道具有相同底层类型的类型化数组。

`"[rgb]"` 格式类似，但不包含 alpha 通道。

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
Bun.color("hsl(0, 0%, 50%)", "[rgb]"); // [128, 128, 128]
Bun.color("red", "[rgb]"); // [255, 0, 0]
Bun.color(0xff0000, "[rgb]"); // [255, 0, 0]
Bun.color({ r: 255, g: 0, b: 0 }, "[rgb]"); // [255, 0, 0]
Bun.color([255, 0, 0], "[rgb]"); // [255, 0, 0]
```

### 将颜色格式化为十六进制字符串

`"hex"` 格式输出小写十六进制字符串，用于 CSS 或其他场景。

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
Bun.color("hsl(0, 0%, 50%)", "hex"); // "#808080"
Bun.color("red", "hex"); // "#ff0000"
Bun.color(0xff0000, "hex"); // "#ff0000"
Bun.color({ r: 255, g: 0, b: 0 }, "hex"); // "#ff0000"
Bun.color([255, 0, 0], "hex"); // "#ff0000"
```

`"HEX"` 格式类似，但输出大写字母的十六进制字符串。

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
Bun.color("hsl(0, 0%, 50%)", "HEX"); // "#808080"
Bun.color("red", "HEX"); // "#FF0000"
Bun.color(0xff0000, "HEX"); // "#FF0000"
Bun.color({ r: 255, g: 0, b: 0 }, "HEX"); // "#FF0000"
Bun.color([255, 0, 0], "HEX"); // "#FF0000"
```

### 打包时在客户端格式化颜色

像 Bun 的许多 API 一样，你可以使用宏在打包时调用 `Bun.color`，以在客户端 JavaScript 构建中使用：

```ts client-side.ts theme={"theme":{"light":"github-light","dark":"dracula"}}
import { color } from "bun" with { type: "macro" };

console.log(color("#f00", "css"));
```

然后，构建客户端代码：

```sh theme={"theme":{"light":"github-light","dark":"dracula"}}
bun build ./client-side.ts
```

这将输出以下内容到 `client-side.js`：

```js theme={"theme":{"light":"github-light","dark":"dracula"}}
// client-side.ts
console.log("red");
```