Color Swatch Pickerv1.0.0
فهرستی از رنگ‌های از پیش‌تعیین‌شده (پالت برند، رنگ برچسب، رنگ تم) که کاربر با کلیک یا کیبورد یکی را انتخاب می‌کند: برخلاف ColorPicker که هر رنگی را می‌سازد، این فقط بین گزینه‌های ثابت یکی را برمی‌گزیند.
این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نصب
با CLI اختصاصی digdesign کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.
npx digdesign@latest add https://docs.digdesign.ir/r/color-swatch-picker.jsonpnpm dlx digdesign@latest add https://docs.digdesign.ir/r/color-swatch-picker.jsonyarn dlx digdesign@latest add https://docs.digdesign.ir/r/color-swatch-picker.jsonbunx --bun digdesign@latest add https://docs.digdesign.ir/r/color-swatch-picker.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
استفاده
import { ColorSwatchPicker, ColorSwatchPickerItem } from "@/components/ui/color-swatch-picker"
<ColorSwatchPicker defaultValue="#6366f1" onValueChange={(color) => console.log(color)}>
<ColorSwatchPickerItem color="#ef4444" />
<ColorSwatchPickerItem color="#6366f1" />
</ColorSwatchPicker>این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
ترکیب اجزا
دسترس‌پذیری
- فقط یک آیتم (انتخاب‌شده، یا اولی اگر هنوز چیزی انتخاب نشده) در چرخهٔ Tab است؛ داخل گروه با پیکان‌ها جابه‌جا شوید: دقیقاً مثل هر radiogroup استاندارد.
- پیکان‌های چپ/راست در RTL خودکار برعکس می‌شوند (بالا/پایین هم مثل چپ/راست عمل می‌کنند تا در چیدمان‌های چندردیفه هم قابل‌پیمایش بماند).
- هر جفت از هشت رنگ --chart-1 تا --chart-8 برای کوررنگی protan و deutan سنجیده شده و از هم جداست؛ با این حال رنگ نباید تنها نشانه باشد (کوررنگی کامل، چاپ سیاه‌وسفید، رنگ‌های سفارشی). label بدهید تا نام رنگ با hover یا فوکوس در tooltip بیاید، و نام رنگ انتخاب‌شده را به متن هم نشان دهید.
- ColorSwatchPicker خودش برچسب قابل‌دیدن ندارد؛ Label را با id بسازید و با aria-labelledby به گروه وصل کنید تا صفحه‌خوان نام گروه را بخواند.
- هر آیتم aria-label خودکار از کد رنگش می‌سازد (مثل «رنگ #6366f1»)؛ اگر رنگ‌ها معنای خاصی دارند (مثل «قرمز فوری») یا رنگ یک توکن CSS است، prop label بدهید تا صفحه‌خوان نام رنگ را بخواند، نه کد یا «رنگ» خالی.
- روی رنگ انتخاب‌شده یک تیک روی دایرهٔ کوچکِ رنگ پس‌زمینه نشان داده می‌شود؛ کنتراستش به روشنی یا تیرگی خود رنگ بستگی ندارد، پس برای توکن‌هایی که با تم عوض می‌شوند هم در هر دو تم خواناست.
مرجع API
ColorSwatchPicker
تمام ویژگی‌های استاندارد div نیز پشتیبانی می‌شود.
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value | string | — | value آیتم انتخاب‌شده در حالت کنترل‌شده (اگر آیتم value نداشته باشد، همان color). |
| defaultValue | string | — | مقدار اولیه در حالت کنترل‌نشده. |
| onValueChange | (value: string) => void | — | با انتخاب یک آیتم صدا زده می‌شود. |
| disabled | boolean | — | غیرفعال‌کردن کل گروه. |
| size | "sm" | "md" | "lg" | "md" | اندازهٔ همهٔ سواچ‌های داخل گروه. |
| radius | "none" | "sm" | "md" | "full" | "md" | شعاع گوشهٔ همهٔ سواچ‌های داخل گروه. |
ColorSwatchPickerItem
تمام ویژگی‌های استاندارد button نیز پشتیبانی می‌شود.
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| color | string | — | رنگ نمایشی: hex/rgb/hsl یا توکن CSS مثل "var(--chart-3)" که مرورگر resolve می‌کند و با تم عوض می‌شود. |
| value | string | color | شناسهٔ گزینه که به onValueChange می‌رسد؛ برای رنگ دسته‌ها شناسهٔ پایدار بدهید. |
| label | string | — | نام رنگ، مثل «قرمز»؛ aria-label می‌شود و با hover یا فوکوس در tooltip دیده می‌شود. |
| disabled | boolean | — | خارج‌کردن این گزینه از انتخاب و Tab. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
نمونه‌ها
Category Colors With Tokens
برای رنگ دسته‌ها به‌جای hex یا پله‌های خام پالت (مثل bg-amber-500) از توکن‌های --chart-1 تا --chart-8 استفاده کنید؛ برای کوررنگی و کنتراست در هر دو تم سنجیده شده‌اند و با عوض‌شدن تم خودشان عوض می‌شوند. value را شناسهٔ پایدار بگذارید (مثل "red") و label را نام فارسی رنگ، تا دادهٔ ذخیره‌شده به مقدار رنگ وابسته نباشد. label با hover یا فوکوس در tooltip دیده می‌شود؛ نام رنگ انتخاب‌شده را به متن هم کنار انتخابگر نشان دهید تا رنگ تنها نشانه نباشد. --chart-1 از رنگ برند می‌آید و در برند پیش‌فرض خاکستری است. برای برچسب گروه، Label را با aria-labelledby به ColorSwatchPicker وصل کنید. برای انتخاب رنگ ToggleGroup را جایگزین نکنید؛ آن الگوی toolbar است و معنای «یکی از چند رنگ» را به صفحه‌خوان نمی‌رساند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Basic
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Sizes
size/radius را روی خودِ ColorSwatchPicker بدهید.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Radius
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Disabled Item
یک گزینهٔ خاص را با disabled از انتخاب خارج کنید؛ در چرخهٔ Tab هم نمی‌آید.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Controlled
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار می‌آید |
|---|---|
| Category Colors With Tokens | انتخاب رنگ دسته یا برچسب که باید در تم روشن و تیره هر دو درست و از هم تفکیک‌پذیر بماند |
| Basic | انتخاب رنگ برچسب یا تگ از پالت رنگ‌های برند در یک ابزار مدیریت پروژه |
| Sizes | size/radius را روی خودِ ColorSwatchPicker بدهید. |
| Radius | سواچ‌های گرد در انتخابگر رنگ تم که با استایل بصری دایره‌ای برند هماهنگ است |
| Disabled Item | یک گزینهٔ خاص را با disabled از انتخاب خارج کنید؛ در چرخهٔ Tab هم نمی‌آید. |
| Controlled | شخصی‌سازی تم زنده که رنگ انتخاب‌شده باید با پیش‌نمایش بیرونی همگام بماند |
دستورالعمل استفاده
برای پالت محدود از این، برای رنگ آزاد از ColorPicker استفاده کنید
انجام بده
وقتی گزینه‌ها از پیش مشخص‌اند (مثل رنگ‌های برند)، ColorSwatchPicker سریع‌تر و قابل‌پیش‌بینی‌تر است.
(به‌جای این پالت ثابت، از ColorPicker کامل استفاده نکنید.)
انجام نده
مجبورکردن کاربر به انتخاب از یک ColorPicker کامل وقتی فقط چند گزینهٔ ثابت مجازند، کار اضافه و امکان خروج از پالت مجاز را باز می‌کند.