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 和 tinycolor2 的替代方案，但它完全支持解析 CSS 顏色字符串，並且零依賴直接內置到 Bun 中。

靈活的輸入

你可以傳入以下任何內容：

• 標准 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 等中使用。它返回顏色最緊湊的字符串表示形式。

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 轉義碼以供在終端中使用，使文本彩色化。

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 顏色以供在終端中使用，使文本彩色化。24 位顏色意味著你可以在支持的終端上顯示 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 種 ANSI 顏色中最接近的顏色。

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 使用的算法。

16 ANSI 顏色（ansi-16）

"ansi-16" 格式將輸入顏色近似為大多數終端支持的 16 種 ANSI 顏色中最接近的顏色。

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 種 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" 格式輸出小寫十六進制字符串以供在 CSS 或其他上下文中使用。

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

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

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

然後，構建客戶端代碼：

bun build ./client-side.ts

這將在 client-side.js 中輸出以下內容：

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