> ## Documentation Index
> Fetch the complete documentation index at: https://bun.ll1025.cn/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[91m"`                     |
| `"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]`            |

你可以用它来：

* 验证并规范化颜色以持久化到数据库（`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) 的内置替代方案，完全支持解析 CSS 颜色字符串，且零依赖。

### 灵活的输入

`Bun.color` 接受以下任意输入：

* 标准 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={null}
Bun.color("red", "css"); // "red"
Bun.color(0xff0000, "css"); // "red"
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={null}
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"
```

`"ansi"` 格式会根据环境变量检测标准输出的色深，并相应选择 `"ansi-16m"`、`"ansi-256"` 或 `"ansi-16"`。如果标准输出不支持任何形式的 ANSI 颜色，则返回空字符串。与 Bun 的其他颜色 API 一样，如果输入未知或解析失败，返回 `null`。

#### 24 位 ANSI 颜色（`ansi-16m`）

`"ansi-16m"` 格式输出 24 位 ANSI 颜色，可以显示 1600 万种颜色，但需要支持它们的现代终端。

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

```ts theme={null}
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 种 ANSI 颜色（某些终端支持）。

```ts theme={null}
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 种 ANSI 颜色之一，我们移植了 [`tmux` 使用的算法](https://github.com/tmux/tmux/blob/dae2868d1227b95fd076fb4a5efa6256c7245943/colour.c#L44-L55)。

#### 16 ANSI 颜色（`ansi-16`）

`"ansi-16"` 格式将输入颜色近似为最近的 16 种 ANSI 颜色（大多数终端支持）。

```ts theme={null}
Bun.color("red", "ansi-16"); // "\u001b[91m"
Bun.color(0xff0000, "ansi-16"); // "\u001b[91m"
Bun.color("#f00", "ansi-16"); // "\u001b[91m"
Bun.color("#ff0000", "ansi-16"); // "\u001b[91m"
```

Bun 先将输入转换为 24 位 RGB 颜色空间，然后转换到 `ansi-256`，再转换到最近的 16 种 ANSI 颜色。

### 格式化为数字

`"number"` 格式将颜色输出为 24 位数字，是适合数据库和配置的紧凑表示。

```ts theme={null}
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={null}
type RGBAObject = {
  // 0 - 255
  r: number;
  // 0 - 255
  g: number;
  // 0 - 255
  b: number;
  // 0 - 1
  a: number;
};
```

示例：

```ts theme={null}
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={null}
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={null}
// 所有值均为 0 - 255
type RGBAArray = [number, number, number, number];
```

示例：

```ts theme={null}
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={null}
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"` 格式输出小写十六进制字符串。

```ts theme={null}
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={null}
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 一样，你可以在打包时使用[宏](/bundler/macros)调用 `Bun.color`，用于客户端 JavaScript 构建：

```ts client-side.ts theme={null}
import { color } from "bun" with { type: "macro" };

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

然后，构建客户端代码：

```sh theme={null}
bun build ./client-side.ts
```

`bun build` 将以下内容写入 `client-side.js`：

```js theme={null}
// client-side.ts
console.log("red");
```