颜色 - Bun 中文文档

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 和 tinycolor2 的内置替代方案，完整支持解析 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-in-JS 的有效 CSS。它会返回颜色最紧凑的字符串表示形式。

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 转义码。

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 颜色。

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 色之一。

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。

16 色 ANSI (`ansi-16`)

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

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 位数字，这是适用于数据库和配置的紧凑表示形式。

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 通道的对象。

type RGBAObject = {
  // 0 - 255
  r: number;
  // 0 - 255
  g: number;
  // 0 - 255
  b: number;
  // 0 - 1
  a: number;
};

示例：

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 通道。

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 通道的数组。

// 所有值范围 0 - 255
type RGBAArray = [number, number, number, number];

示例：

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 通道。

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" 格式输出小写十六进制字符串。

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" 格式相同，但输出大写字母。

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 构建中使用：

client-side.ts

import { color } from "bun" with { type: "macro" };

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

然后，构建客户端代码：

bun build ./client-side.ts

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

// client-side.ts
console.log("red");

开始使用

核心运行时

文件与模块系统

HTTP 服务器

网络通信

数据与存储

并发

进程与系统

交互与工具链

实用工具

标准与兼容性

贡献

颜色

灵活的输入

将颜色格式化为 CSS

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

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

256 色 ANSI (`ansi-256`)

16 色 ANSI (`ansi-16`)

将颜色格式化为数字

获取红、绿、蓝和 alpha 通道

`{rgba}` 对象

`[rgba]` 数组

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

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

​灵活的输入

​将颜色格式化为 CSS

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

​24 位 ANSI 颜色 (ansi-16m)

​256 色 ANSI (ansi-256)

​16 色 ANSI (ansi-16)

​将颜色格式化为数字

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

​{rgba} 对象

​[rgba] 数组

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

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

灵活的输入

将颜色格式化为 CSS

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

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

256 色 ANSI (`ansi-256`)

16 色 ANSI (`ansi-16`)

将颜色格式化为数字

获取红、绿、蓝和 alpha 通道

`{rgba}` 对象

`[rgba]` 数组

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

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