Bun.color(input, outputFormat?) использует CSS-парсер Bun для разбора, нормализации и преобразования цветов из пользовательского ввода в различные выходные форматы, включая:

Формат	Пример
"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 в зависимости от того, сколько цветов поддерживает терминал)
• Форматирование цветов для использования в CSS, внедрённом в HTML
• Получение компонентов цвета r, g, b и a как JavaScript-объектов или чисел из строки цвета CSS

Вы можете думать об этом как об альтернативе популярным npm-пакетам color и tinycolor2, но с полной поддержкой разбора строк цветов CSS и без зависимостей, встроенных непосредственно в Bun.

Гибкий ввод

Вы можете передать любое из следующих значений:

• Стандартные имена цветов CSS, такие как "red"
• Числа, такие как 0xff0000
• Hex-строки, такие как "#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-цвета, он возвращает пустую строку. Как и остальной цветовой API Bun, если ввод неизвестен или не удаётся разобрать, он возвращает null.

24-битные ANSI-цвета (ansi-16m)

Формат "ansi-16m" выводит 24-битные ANSI-цвета для использования в терминалах для цветного текста. 24-битный цвет означает, что вы можете отображать 16 миллионов цветов на поддерживаемых терминалах и требует современный терминал, который поддерживает это.

Это преобразует входной цвет в 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

Получение красного, зелёного, синего и альфа-каналов

Вы можете использовать форматы "{rgba}", "{rgb}", "[rgba]" и "[rgb]" для получения красного, зелёного, синего и альфа-каналов как объектов или массивов.

Объект {rgba}

Формат "{rgba}" выводит объект с красным, зелёным, синим и альфа-каналами.

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}" похож, но не включает альфа-канал.

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]" выводит массив с красным, зелёным, синим и альфа-каналами.

// Все значения 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}", альфа-канал — это целое число между 0 и 255. Это полезно для типизированных массивов, где каждый канал должен быть одного базового типа.

Формат "[rgb]" похож, но не включает альфа-канал.

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-строк

Формат "hex" выводит 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" похож, но выводит 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"

Форматирование цветов на стороне клиента во время сборки

Как и многие API Bun, вы можете использовать макросы для вызова 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");