Switchv1.0.0
کلیدی برای روشن و خاموش کردن یک تنظیم؛ با انیمیشن سازگار با چیدمان راست‌به‌چپ.
این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نصب
با CLI اختصاصی digdesign کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.
npx digdesign@latest add https://docs.digdesign.ir/r/switch.jsonpnpm dlx digdesign@latest add https://docs.digdesign.ir/r/switch.jsonyarn dlx digdesign@latest add https://docs.digdesign.ir/r/switch.jsonbunx --bun digdesign@latest add https://docs.digdesign.ir/r/switch.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
استفاده
import { Switch } from "@/components/ui/switch"
<Switch defaultChecked />این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
دسترس‌پذیری
- با کلید Space تغییر وضعیت می‌دهد و نقش switch را اعلام می‌کند.
- همیشه با یک Label همراهش کنید یا aria-label بدهید تا صفحه‌خوان هدف کلید را بداند.
- readOnly برخلاف disabled، کلید را از چرخهٔ Tab و صفحه‌خوان حذف نمی‌کند؛ فقط جلوی تغییر مقدار را می‌گیرد.
- invalid مقدار aria-invalid را ست می‌کند تا صفحه‌خوان وضعیت نامعتبر را همراه با متن خطای کنارش اعلام کند.
مرجع API
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| checked | boolean | — | وضعیت کنترل‌شدهٔ کلید. |
| defaultChecked | boolean | false | وضعیت اولیه در حالت کنترل‌نشده. |
| onCheckedChange | (checked: boolean) => void | — | با هر تغییر وضعیت صدا زده می‌شود. |
| size | "sm" | "md" | "lg" | "md" | اندازهٔ کلید و دستهٔ داخلش. |
| icon | boolean | false | نمایش آیکون تیک داخل دسته در حالت روشن، برای وضوح بیشتر. |
| interaction | "slide" | "stretch" | "peek" | "morph" | "hint" | "slide" | واکنش کلید به فشردن و هاور؛ روی کلید disabled یا readOnly اعمال نمی‌شود. |
| labels | boolean | { on: ReactNode; off: ReactNode } | false | متن وضعیت داخل ریل؛ true یعنی «روشن» و «خاموش». ریل پهن‌تر می‌شود. |
| disabled | boolean | false | غیرفعال کردن کلید و خروج از چرخهٔ Tab. |
| readOnly | boolean | false | برخلاف disabled، در چرخهٔ Tab می‌ماند و ظاهر عادی دارد؛ فقط تغییر مقدار را می‌گیرد. |
| invalid | boolean | false | وضعیت نامعتبر برای فرم‌ها؛ aria-invalid و رنگ خطا (قرمز) را روشن می‌کند. |
| required | boolean | false | aria-required روی کلید می‌گذارد. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
نمونه‌ها
اندازه‌ها (Sizes)
sm برای فهرست‌های فشرده و جدول‌ها، md پیش‌فرض عمومی، lg برای صفحات تنظیمات با فاصلهٔ بیشتر.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
با آیکون (icon)
icon یک نشانهٔ تیک داخل دستهٔ کلید در حالت روشن نشان می‌دهد؛ وضعیت را حتی بدون توجه به رنگ هم واضح‌تر می‌کند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
اینتراکشن (interaction)
واکنش کلید به فشردن و هاور. slide پیش‌فرض است؛ stretch دسته را هنگام فشردن کش می‌دهد، peek روی هاور باریکه‌ای از حالت بعدی نشان می‌دهد، morph علامت ○ را به | تبدیل می‌کند و hint فلش جهت حرکت را نشان می‌دهد. labels متن وضعیت را داخل ریل می‌گذارد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نامعتبر (Invalid)
برای خطای اعتبارسنجی فرم، invalid بدهید؛ حاشیه قرمز می‌شود و در حالت روشن، رنگ کلید هم به‌جای primary قرمز می‌شود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
فقط‌خواندنی (Read-only)
برخلاف disabled، readOnly ظاهر عادی را حفظ می‌کند و در چرخهٔ Tab می‌ماند؛ فقط جلوی تغییر مقدار با کلیک یا کیبورد را می‌گیرد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Disabled
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
در حال ذخیره (Loading)
وضعیت را قبل از پاسخ سرور عوض نکنید. اگر درخواست شکست بخورد، سوییچ چیزی را نشان می‌دهد که واقعاً فعال نشده. تا پاسخ، سوییچ قفل و aria-busy روشن باشد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار می‌آید |
|---|---|
| اندازه‌ها (Sizes) | sm برای فهرست‌های فشرده و جدول‌ها، md پیش‌فرض عمومی، lg برای صفحات تنظیمات با فاصلهٔ بیشتر. |
| با آیکون (icon) | icon یک نشانهٔ تیک داخل دستهٔ کلید در حالت روشن نشان می‌دهد؛ وضعیت را حتی بدون توجه به رنگ هم واضح‌تر می‌کند. |
| اینتراکشن (interaction) | واکنش کلید به فشردن و هاور |
| نامعتبر (Invalid) | برای خطای اعتبارسنجی فرم، invalid بدهید؛ حاشیه قرمز می‌شود و در حالت روشن، رنگ کلید هم به‌جای primary قرمز می‌شود. |
| فقط‌خواندنی (Read-only) | برخلاف disabled، readOnly ظاهر عادی را حفظ می‌کند و در چرخهٔ Tab می‌ماند؛ فقط جلوی تغییر مقدار با کلیک یا کیبورد را می‌گیرد. |
| Disabled | تنظیمی که به پلن یا سطح دسترسی کاربر بستگی دارد |
| در حال ذخیره (Loading) | تنظیمی که بلافاصله به سرور می‌رود، مثل احراز هویت دو مرحله‌ای |
دستورالعمل استفاده
فقط برای تغییری که فوری اعمال می‌شود
انجام بده
Switch وضعیتی را نشان می‌دهد که با تغییر آن بلافاصله فعال می‌شود، بدون نیاز به دکمهٔ ذخیرهٔ جدا؛ برای تنظیمات آنی مثل حالت پرواز مناسب است.
انجام نده
اگر تغییر باید با یک عمل جدا (مثل دکمهٔ «ذخیره») تأیید شود، Switch گمراه‌کننده است؛ در فرم‌هایی که با ثبت ارسال می‌شوند از Checkbox استفاده کنید.
برچسب همیشه همراه کلید
انجام بده
برچسب را با Label و htmlFor به کلید وصل کنید تا هم روی متن هم روی کلید بشود کلیک کرد و صفحه‌خوان هدف را بگوید.
انجام نده
کلید تنها بدون برچسب یا aria-label، برای کاربر صفحه‌خوان فقط یک «کلید، خاموش» بی‌نام است؛ معلوم نیست چه چیزی را روشن می‌کند.
آیکون فقط برای وضوح بیشتر، نه تزیین
انجام بده
icon را وقتی اضافه کنید که تشخیص روشن/خاموش بودن با رنگ به‌تنهایی سخت است (مثلاً فهرست فشرده یا کاربران کم‌بین)؛ خودِ آیکون تیک تضاد را بیشتر می‌کند.
انجام نده
برای هر Switch عادی در صفحه icon را روشن نکنید؛ در فهرست‌های بلند شلوغ می‌شود و چیزی به فهم کاربر اضافه نمی‌کند.