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,
)

پارامترها

Properties

Methods

Rgb

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

سازنده

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

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

Rgba

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

سازنده

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

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

Hsl

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

سازنده

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

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

Hsla

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

سازنده

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

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

ColorScheme

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

سازنده

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

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

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

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

توابع تبدیل

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

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

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

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

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

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

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

الگوهای قالب

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

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 تنها در پایانه‌ای که آن‌ها را می‌فهمد به شکل آرایش دیده می‌شوند؛ در کنسول مرورگر همان نویسه‌های کنترلی خام به چشم می‌آیند.