色彩 – API | Bun 文件 - Bun 繁體中文

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 通道的陣列。

// All values are 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 建置中

client-side.ts
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");