Color

سامانه‌ای رنگی بر پایهٔ کلاس، با یاری‌رسان‌های تبدیل برای کار با RGB، RGBA، HSL، HSLA، HSB/HSV و رنگ‌های شانزده‌شانزدهی. در آن یک کلاس پرتوان Color، کلاس‌های مقدارِ تغییرناپذیر (Rgb، Rgba، Hsl، Hsla)، سازندهٔ پالت ColorScheme، دسته‌ای تابع تبدیل مستقل، و FMT یعنی نقشهٔ سبک‌های ANSI برای پایانه آمده است.

یاری‌رسان‌های ساده‌تر یعنی hexToRgb، rgbToHex و randomColor صفحهٔ خودشان را دارند: hexToRgb، rgbToHex، randomColor. هر سه از همین ماژول دوباره صادر می‌شوند.

API

Color

کلاس اصلی رنگ. یک رشتهٔ شانزده‌شانزدهی، یک آرایهٔ [r, g, b, a]، یا عددهای جدا برای هر کانال می‌پذیرد و بی‌درنگ همهٔ بازنمایی‌ها (rgb، rgba، hex، hsl، hsla) را به‌همراه دسترسی مستقیم به تک‌تک کانال‌ها حساب می‌کند.

سازنده

new Color(
  r: string | number | Array<string | number>,
  g?: string | number,
  b?: string | number,
  a?: string | number,
)

پارامترها

پارامتر	توضیح	نوع	پیش‌فرض
r	کانال قرمز. یک رشتهٔ شانزده‌شانزدهی (#f00 یا #ff0000، با # یا بدون آن)، یک آرایهٔ [r, g, b, a?]، یا یک عدد	string | number | Array<string | number>	الزامی
g	کانال سبز (وقتی r رشته یا آرایه باشد نادیده گرفته می‌شود)	string | number	0
b	کانال آبی (وقتی r رشته یا آرایه باشد نادیده گرفته می‌شود)	string | number	0
a	کانال آلفا (۰ تا ۱)	string | number	1.0

Properties

ویژگی	توضیح	نوع
r	کانال قرمز (۰ تا ۲۵۵)	string | number
g	کانال سبز (۰ تا ۲۵۵)	string | number
b	کانال آبی (۰ تا ۲۵۵)	string | number
a	کانال آلفا (۰ تا ۱)	string | number
h	فام (۰ تا ۳۶۰)، پابه‌پای hsl.h	string | number
s	اشباع (۰ تا ۱۰۰)، پابه‌پای hsl.s	string | number
l	روشنایی (۰ تا ۱۰۰)، پابه‌پای hsl.l	string | number
rgb	شیء مقدار RGB	Rgb
rgba	شیء مقدار RGBA	Rgba
hex	رشتهٔ شانزده‌شانزدهی (مثلاً #ff0000)	string
hsl	شیء مقدار HSL	Hsl
hsla	شیء مقدار HSLA	Hsla

Methods

متد	توضیح	مقدار بازگشتی
setHue(newHue)	فام را تعیین می‌کند و RGB و شانزده‌شانزدهی را از روی HSL از نو حساب می‌کند	void
setSat(newSat)	اشباع را تعیین می‌کند و RGB و شانزده‌شانزدهی را از روی HSL از نو حساب می‌کند	void
setLum(newLum)	روشنایی را تعیین می‌کند و RGB و شانزده‌شانزدهی را از روی HSL از نو حساب می‌کند	void
setAlpha(newAlpha)	آلفا را هم در rgba و هم در hsla می‌گذارد (به RGB و شانزده‌شانزدهی دست نمی‌زند)	void
updateFromHsl()	rgb، کانال‌ها و hex را از روی h/s/l کنونی از نو حساب می‌کند (تنظیم‌کننده‌های بالا صدایش می‌زنند)	void

Rgb

شیء مقدار RGB که از یک آرایه ساخته می‌شود. toString() رشتهٔ CSS به شکل rgb(...) برمی‌گرداند.

سازنده

new Rgb(col: Array<string | number>) // [r, g, b]

ویژگی‌ها و متدها

عضو	توضیح	نوع
r	کانال قرمز	string | number
g	کانال سبز	string | number
b	کانال آبی	string | number
toString()	rgb(r,g,b) برمی‌گرداند	string

Rgba

Rgb را با یک کانال آلفا گسترش می‌دهد. toString() رشتهٔ CSS به شکل rgba(...) برمی‌گرداند.

سازنده

new Rgba(col: Array<string | number>) // [r, g, b, a]

ویژگی‌ها و متدها

عضو	توضیح	نوع
r g b	به ارث رسیده از Rgb	string | number
a	کانال آلفا	string | number
toString()	rgba(r,g,b,a) برمی‌گرداند	string

Hsl

شیء مقدار HSL که از یک آرایه ساخته می‌شود. toString() رشتهٔ CSS به شکل hsl(...) برمی‌گرداند.

سازنده

new Hsl(col: Array<string | number>) // [h, s, l]

ویژگی‌ها و متدها

عضو	توضیح	نوع
h	فام (۰ تا ۳۶۰)	string | number
s	اشباع (۰ تا ۱۰۰)	string | number
l	روشنایی (۰ تا ۱۰۰)	string | number
toString()	hsl(h,s%,l%) برمی‌گرداند	string

Hsla

Hsl را با یک کانال آلفا گسترش می‌دهد. toString() رشتهٔ CSS به شکل hsla(...) برمی‌گرداند.

سازنده

new Hsla(col: Array<string | number>) // [h, s, l, a]

ویژگی‌ها و متدها

عضو	توضیح	نوع
h s l	به ارث رسیده از Hsl	string | number
a	کانال آلفا	string | number
toString()	hsla(h,s%,l%,a) برمی‌گرداند	string

ColorScheme

پالتی از شیءهای Color خویشاوند می‌سازد؛ یا یکراست از فهرستی از رنگ‌ها، یا از یک رنگ پایه که به اندازهٔ آرایه‌ای از زاویه‌های فام چرخانده می‌شود. متدهای کارخانهٔ ایستا، طرح‌های هم‌نشینی رنگ رایج را پوشش می‌دهند.

سازنده

new ColorScheme(colorVal: (string | number)[], angleArray: number[])

پارامتر	توضیح	نوع
colorVal	رنگ پایه، یا وقتی angleArray برابر undefined باشد، آرایه‌ای از رنگ‌ها که پالت از آن ساخته می‌شود	(string | number)[]
angleArray	جابه‌جایی‌های فام (بر حسب درجه) که بر رنگ پایه اعمال می‌شود تا باقی مدخل‌های پالت به دست آید	number[]

ویژگی‌ها و متدها

عضو	توضیح	مقدار بازگشتی
palette	رنگ‌هایی که ساخته شده‌اند	Color[]
createFromColors(colorVal)	پالت را از روی آرایه‌ای از رنگ‌ها می‌سازد	Color[]
createFromAngles(colorVal, angleArray)	پالت را از روی یک رنگ پایه و جابه‌جایی‌های فام می‌سازد	Color[]

متدهای کارخانهٔ ایستا

هر کدام یک مقدار رنگ پایه می‌گیرند و ColorSchemeی برمی‌گردانند که مجموعهٔ زاویه‌های فامش از پیش تعیین شده است.

متد	زاویه‌های فام	طرح
ColorScheme.Compl(colorVal)	[180]	مکمل
ColorScheme.Triad(colorVal)	[120, 240]	سه‌تایی
ColorScheme.Tetrad(colorVal)	[60, 180, 240]	چهارتایی
ColorScheme.Analog(colorVal)	[-45, 45]	هم‌جوار
ColorScheme.Split(colorVal)	[150, 210]	مکمل شکافته
ColorScheme.Accent(colorVal)	[-45, 45, 180]	هم‌جوار با تأکید

توابع تبدیل

توابعی مستقل که Color در درون خود به کار می‌برد؛ همه صادر شده‌اند تا مستقیم هم بتوانی از آن‌ها استفاده کنی. آنجا که تابعی سه کانال می‌گیرد، آرگومان نخست می‌تواند یک آرایهٔ تنها هم باشد (مثلاً rgbToHsl([r, g, b])).

تابع	توضیح	امضا
componentToHex(c)	یک کانال ۰ تا ۲۵۵ را به رشتهٔ شانزده‌شانزدهی دورقمی تبدیل می‌کند	(c: string | number) => string
hue2rgb(p, q, t)	یاری‌رسان فام برای رفتن از HSL به RGB (که hslToRgb به کار می‌برد)	(p: number, q: number, t: number) => number
hslToRgb(h, s, l)	از HSL به [r, g, b] (۰ تا ۲۵۵). آرگومان نخست می‌تواند [h, s, l] باشد	(h, s, l) => number[]
rgbToHsl(r, g, b)	از RGB به [h, s, l]. آرگومان نخست می‌تواند [r, g, b] باشد	(r, g, b) => number[]
rgbToHsb(r, g, b)	از RGB به [h, s, b] (HSB/HSV)	(r: number, g: number, b: number) => number[]
hsbToRgb(h, s, v)	از HSB/HSV به [r, g, b] (۰ تا ۲۵۵)	(h: number, s: number, v: number) => number[]
hsvToRgb(h, s, v)	نام دیگری برای hsbToRgb	(h: number, s: number, v: number) => number[]
hsvToHsl(h, s, b)	از HSB/HSV به [h, s, l] (از راه rgbToHsl(hsbToRgb(...)))	(h, s, b) => number[]
rgbToHsv(r, g, b)	نام دیگری برای rgbToHsb	(r: number, g: number, b: number) => number[]
hexToHsb(hex)	از #rrggbb یا #rgb به [h, s, b]، و اگر ورودی بدشکل باشد null	(hex: string) => number[] | null
hexToHsv(hex)	نام دیگری برای hexToHsb	(hex: string) => number[] | null
hsbToHsl(h, s, b)	از HSB/HSV به [h, s, l]	(h, s, b) => number[]
hslToHsb(h, s, l)	از HSL به [h, s, b]	(h, s, l) => number[]
hslToHsv(h, s, l)	نام دیگری برای hslToHsb	(h, s, l) => number[]

componentToHex، rgbToHex و hexToRgb قطعه‌های سطح پایین‌اند؛ rgbToHex و hexToRgb را ببین.

یاری‌رسان‌های آلفا

آلفا اینجا از ۰ تا ۱۰۰ بیان می‌شود؛ همان مقیاس درصدی که بقیهٔ این ماژول برای اشباع و روشنایی به کار می‌برد، نه آن ۰ تا ۱ که rgba() در CSS می‌گیرد.

تابع	توضیح	امضا
hexToAlpha(aa)	از کانال آلفای شانزده‌شانزدهی دورقمی (ff، 80، 00) به مقداری میان ۰ تا ۱۰۰	(aa: string) => number
rgbaString(r,g,b,a)	یک رشتهٔ CSS به شکل rgba() می‌سازد؛ a بر ۱۰۰ تقسیم می‌شود	(r, g, b, a) => string
rgbaToRgb(r,g,b,a)	رنگی نیمه‌شفاف را روی سفید می‌نشاند و [r, g, b] مات برمی‌گرداند	(r, g, b, a) => number[]
rgbaToHex(r,g,b,a)	همان ترکیب، که به شکل رشتهٔ شانزده‌شانزدهی شش‌رقمی برگردانده می‌شود	(r, g, b, a) => string

WARNING

rgbaToRgb و rgbaToHex پس‌زمینه را سفید میخ‌کوب کرده‌اند. این‌ها برای جاهایی هستند که کانال آلفا نمی‌پذیرند (مثلاً وقتی باید یک شانزده‌شانزدهی شش‌رقمی بازنویسی شود). زیر یک پوستهٔ تیره نتیجه بیش از حد روشن به نظر می‌آید؛ در آن صورت روی پس‌زمینهٔ خودت بیامیز.

یاری‌رسان‌های آمیزش و ریاضیات سایه‌زن

همان ریاضیات آمیزش و تنظیم رنگ که پشت پالایه‌های پس‌پردازش ranuts/visual (یعنی ColorAdjustFilter و همراهانش) کار می‌کند و اینجا صادر شده تا در سمت CPU هم به کار آید (مثلاً برای حساب کردن پیش‌نمای یک بندانگشتی، بی‌آنکه خط لولهٔ GPU برپا شود). برخلاف بقیهٔ این ماژول، کانال‌ها اینجا از ۰ تا ۱‌اند، نه ۰ تا ۲۵۵ و نه ۰ تا ۱۰۰؛ همان قراری که سایه‌زن‌ها دارند.

تابع	توضیح	امضا
luma(r, g, b)	روشنایی آن‌گونه که چشم درمی‌یابد (وزن‌های Rec. 601). هر مقیاسی که ورودی‌ها داشته باشند (۰ تا ۱ یا ۰ تا ۲۵۵) نگه می‌دارد	(r, g, b) => number
blendScreen(base, blend)	آمیزش screen: برای هر کانال 1 - (1-base)(1-blend)	(base: RGB, blend: RGB) => RGB
blendMultiply(base, blend)	آمیزش ضربی: برای هر کانال base * blend	(base: RGB, blend: RGB) => RGB
blendOverlay(base, blend)	روی‌هم‌گذاری: در سایه‌ها ضرب، در روشنایی‌ها screen	(base: RGB, blend: RGB) => RGB
brightnessContrast(color, b, c)	برای هر کانال (channel - 0.5) * contrast + 0.5 + brightness	(color: RGB, brightness, contrast) => RGB
saturation(color, amount)	به سوی درخشندگی می‌آمیزد. 0 یعنی خاکستری، 1 یعنی بی‌تغییر، و بیش از 1 یعنی اشباع‌تر	(color: RGB, amount: number) => RGB
vibrance(color, amount)	مانند saturation، اما کانال‌های کم‌رمق را بیش از کانال‌های از پیش پرمایه بالا می‌برد. بیش از 0 تقویت می‌کند و کمتر از آن فرو می‌نشاند	(color: RGB, amount: number) => RGB
cosinePalette(t, a, b, c, d)	گرادیان کسینوسی اینیگو کیلز: a + b·cos(2π(c·t + d))، که در آن a تا d هرکدام سه‌تایی RGB‌اند و t جای‌گیری میان ۰ و ۱	(t, a: RGB, b: RGB, c: RGB, d: RGB) => RGB
srgbToLinear(c) / linearToSrgb(c)	یک کانال را میان sRGB (آنچه از یک رنگ شانزده‌شانزدهی می‌خوانی) و نور خطی (آنچه ریاضیات سایه‌زن می‌خواهد) تبدیل می‌کند	(c: number) => number

import { blendScreen, brightnessContrast, cosinePalette, srgbToLinear, linearToSrgb } from 'ranuts/utils';

// آمیختن دو رنگ ۰ تا ۱ با حالت screen
const screened = blendScreen([0.8, 0.2, 0.1], [0.1, 0.5, 0.9]);

// بالا بردن کنتراست و کمی پایین آوردن روشنایی
const graded = brightnessContrast([0.6, 0.6, 0.6], -0.05, 1.2);

// نمونه‌برداری از یک پالت گرادیان رویه‌ای در t=0.35
const swatch = cosinePalette(0.35, [0.5, 0.5, 0.5], [0.5, 0.5, 0.5], [1, 1, 1], [0, 0.33, 0.67]);

// ریاضیاتی که گاما را درست می‌بیند (آمیزش، نورپردازی) باید در فضای خطی انجام شود
const linear = srgbToLinear(0.5);
const backToSrgb = linearToSrgb(linear); // ≈ 0.5

WARNING

ریاضیات آمیزش و تنظیم رنگ برای آنکه نتیجه از نظر فیزیکی درست دربیاید، بر مقادیر نور خطی کار می‌کند. رنگ شانزده‌شانزدهی ۸ بیتی با sRGB کدگذاری شده است، پس اگر می‌خواهی آمیزش نه فقط اجرا شود بلکه درست هم به نظر برسد، نخست آن را از srgbToLinear بگذران.

الگوهای قالب

عبارت‌های باقاعده برای وارسی رشته‌های رنگ. RGB_REGEX و RGBA_REGEX فاصله را تاب نمی‌آورند؛ اول آن‌ها را بردار (value.replace(/\s+/g, '')).

ثابت	با چه چیزی جور می‌شود
HEX_COLOR_REGEX	#rgb یا #rrggbb، که # در آن الزامی است و به بزرگی و کوچکی حرف کاری ندارد
RGB_REGEX	rgb(r,g,b)
RGBA_REGEX	rgba(r,g,b,a)

FMT

دفتری از جفت‌های کد گریز ANSI پایانه، برای آراستن و رنگ کردن متن. هر مدخل یک چندتایی [بازکننده، بندنده] است که رشته را در آن می‌پیچی تا خروجی پایانه آراسته شود.

const FMT: Record<string, Array<string>>;

کلیدهای در دسترس: bold، dim، reset، italic، underline، inverse، hidden، strikethrough، black، red، green، yellow، blue، magenta، cyan، white، gray، و گونه‌های پس‌زمینه‌ای bgBlack، bgRed، bgGreen، bgYellow، bgBlue، bgMagenta، bgCyan، bgWhite.

نمونه

ساختن یک Color

import { Color } from 'ranuts';

// از یک رشتهٔ شانزده‌شانزدهی (شکل کوتاه یا بلند، # اختیاری)
const red = new Color('#ff0000');
console.log(red.hex); // '#ff0000'
console.log(red.rgb.toString()); // 'rgb(255,0,0)'
console.log(red.hsl.toString()); // 'hsl(0,100%,50%)'

// از روی کانال‌ها
const green = new Color(0, 255, 0);
console.log(green.hex); // '#00ff00'

// از یک آرایه (به‌همراه آلفا)
const blue = new Color([0, 0, 255, 0.5]);
console.log(blue.rgba.toString()); // 'rgba(0,0,255,0.5)'

تغییر دادن یک Color از راه HSL

import { Color } from 'ranuts';

const color = new Color('#ff0000');

color.setHue(120); // فام را تا سبز می‌چرخاند
console.log(color.rgb.toString()); // 'rgb(0,255,0)'

color.setLum(25); // تیره‌تر
color.setSat(50); // از اشباع می‌کاهد
color.setAlpha(0.4);
console.log(color.rgba.toString()); // 'rgba(...,0.4)'

ساختن پالت با ColorScheme

import { ColorScheme } from 'ranuts';

// جفت مکمل از روی یک رنگ پایه
const compl = ColorScheme.Compl('#3498db');
console.log(compl.palette.map((c) => c.hex));

// طرح سه‌تایی (رنگ پایه و دو رنگ با فاصلهٔ ۱۲۰ درجه)
const triad = ColorScheme.Triad('#3498db');
console.log(triad.palette.length); // 3

// یکراست از فهرستی از رنگ‌ها
const custom = new ColorScheme(['#ff0000', '#00ff00', '#0000ff']);
console.log(custom.palette.map((c) => c.hsl.toString()));

کار با توابع تبدیل

import { rgbToHsl, hslToRgb, rgbToHsb, hsbToRgb, componentToHex } from 'ranuts';

console.log(rgbToHsl(255, 0, 0)); // [0, 100, 50]
console.log(hslToRgb(0, 100, 50)); // [255, 0, 0]
console.log(rgbToHsb(255, 0, 0)); // [0, 100, 100]
console.log(hsbToRgb(0, 100, 100)); // [255, 0, 0]
console.log(componentToHex(255)); // 'ff'

// هرجا مستند شده باشد، ورودی آرایه‌ای هم پذیرفته می‌شود
console.log(rgbToHsl([0, 128, 255])); // [h, s, l]

آراستن خروجی پایانه با FMT

import { FMT } from 'ranuts';

const [open, close] = FMT.green;
console.log(`${open}success${close}`); // در پایانه، "success" به رنگ سبز

const bold = FMT.bold;
console.log(`${bold[0]}important${bold[1]}`);

یادداشت‌ها

1. همه چیز از همان اول حساب می‌شود: Color همهٔ بازنمایی‌ها را در سازنده حساب می‌کند، پس hex، rgb، rgba، hsl و hsla از لحظهٔ ساخته شدن با هم هم‌خوان‌اند.
2. تنظیم‌کننده‌های HSL، RGB را از نو حساب می‌کنند: setHue، setSat و setLum نخست HSL را به‌روز می‌کنند و سپس با updateFromHsl دوباره RGB و شانزده‌شانزدهی را بیرون می‌کشند. setAlpha تنها به rgba و hsla دست می‌زند.
3. ورودی چه آرایه چه کانال: چند تابع تبدیل (rgbToHex، rgbToHsl، hslToRgb) هم سه کانال جدا می‌پذیرند و هم یک آرایهٔ تنها در آرگومان نخست.
4. HSV در برابر HSB: hsvToRgb نام دیگری برای hsbToRgb است و hsvToHsl نام دیگری برای تبدیل HSB به HSL. اینجا HSV و HSB به یک مدل اشاره دارند.
5. FMT فقط در پایانه معنا دارد: دنباله‌های گریز ANSI تنها در پایانه‌ای که آن‌ها را می‌فهمد به شکل آرایش دیده می‌شوند؛ در کنسول مرورگر همان نویسه‌های کنترلی خام به چشم می‌آیند.