Switch
يشغّل إعدادًا أو يوقفه فورًا. بحجم 48 في 24px، مع أيقونة صح اختيارية، وحالات التمرير والتركيز والقراءة فقط والتعطيل والخطأ.
الإصدار 0.4.1 ·
التثبيت
bunx --bun shadcn@latest add @dga/switchويثبّت Field أيضًا.
الاستخدام
import { Field, FieldContent, FieldLabel } from "@/components/ui/field";
import { Switch } from "@/components/ui/switch";
export function UpdatesField() {
return (
<Field orientation="horizontal" className="items-center justify-between">
<FieldContent>
<FieldLabel>أرسل لي تحديثات عن هذا الطلب</FieldLabel>
</FieldContent>
<Switch name="updates" defaultChecked />
</Field>
);
}استخدم Switch لإعداد يسري لحظة قلبه: الإشعارات أو تشغيل ميزة أو إيقافها. وإن كان الاختيار لا يُطبَّق إلا عند إرسال نموذج فاستخدم Checkbox. سمِّ ما يفعله المفتاح لا حالته: «تحديثات الطلب» لا «قيد التشغيل».
البنية
- المسار (
<span role="switch">مع<input>مخفي): بحجم 48 في 24px. - المقبض: الدائرة البيضاء المنزلقة؛ وفيها أيقونة الصح عند ضبط
icon. - التسمية والنص المساعد والخطأ: من Field. ضع المفتاح بعد FieldContent ليكون في النهاية.
أمثلة
الحالات
متوقف وقيد التشغيل ومع أيقونة وللقراءة فقط ومعطّل وخطأ.
المفتاح في النهاية
ضع Switch بعد FieldContent واستخدم justify-between لقائمة إعدادات، والمفتاح في نهاية كل صف.
RTL
يتحرك المقبض على المحور المنطقي: يبدأ من اليمين وينزلق إلى اليسار عند التشغيل، كما يُقرأ المسار. ولا شيء يُعكس يدويًا؛ والمفتاح الذي في النهاية يقع على اليسار.
إمكانية الوصول
| المفتاح | الإجراء |
|---|---|
| Tab | ينقل التركيز إلى المفتاح. |
| Space | يشغّله أو يوقفه. |
- الدور
switchمعaria-checked، وحقل أصلي مخفي للنماذج. - تأتي التسمية من Field؛ والنقر عليها يقلب المفتاح.
- المسار المتوقف ومقبضه الأبيض، والمسار المشغَّل ومقبضه، بنسبة 3:1 أو أفضل فاتحًا وداكنًا (WCAG 1.4.11). وتظهر الحالة أيضًا من موضع المقبض، لا من اللون وحده.
- التركيز حد بسمك 2px على بعد 2px خارج المسار. ويضيف الخطأ حدًا بسمك 2px ورسالة بأيقونة.
- يحترم تقليل الحركة: يتحرك المقبض دون حركة انتقالية.
مرجع API
Switch
يشغّل إعدادًا أو يوقفه فورًا (في DGA: Switch). استخدم مربع الاختيار للخيارات التي لا تُطبَّق إلا عند إرسال النموذج. سمّه بـ Field (`orientation="horizontal"`).
| الخاصية | النوع | القيمة الافتراضية |
|---|---|---|
booleanيعرض علامة صح داخل المقبض أثناء التشغيل. | false | |
| ||
booleanحالة متحكَّم بها. | لا توجد قيمة افتراضية | |
| ||
booleanالحالة الابتدائية عند عدم التحكم. | لا توجد قيمة افتراضية | |
| ||
booleanيعطّل المفتاح. | لا توجد قيمة افتراضية | |
| ||
stringاسم الحقل عند إرسال النموذج. | لا توجد قيمة افتراضية | |
| ||
(checked: boolean, details) => voidتُستدعى عند قلب المستخدم المفتاح. من Base UI. | لا توجد قيمة افتراضية | |
| ||
booleanيعرض الحالة دون إمكانية تغييرها. | لا توجد قيمة افتراضية | |
| ||
booleanلا يمكن إرسال النموذج قبل تشغيله. | لا توجد قيمة افتراضية | |
| ||
يقبل أيضًا جميع خصائص Base UI Switch (يفتح في نافذة جديدة).
الاختلافات عن DGA
- المسار المتوقف هو
control-border(4.8:1) بدل#ccc(1.6:1)، مع مقبض أبيض (رمز جديدcontrol-thumb). - يبقى المسار المشغَّل green-600 عند التمرير والضغط في الوضع الداكن (انظر Checkbox).
| التغيير | السبب |
|---|---|
--control-thumb (new) | The Switch thumb is white in both modes. Figma has no token for it (background-white turns dark in dark mode, and the white thumb on the off track would be 1.1:1). |
Checkbox, Radio, Switch: focus ring | Keyboard-only focus (WCAG 2.4.7). The outline follows the control's shape and does not shift the label. |
Switch: off track | #ccc is 1.6:1 on white. control-border is 4.8:1, so the off track and its white thumb pass 3:1. |
Switch: error | The error must be visible on the control as well as in the text, without relying on colour alone. |
عرض جميع الاختلافات (4) لهذا المكوّن أسباب الاختلافات مكتوبة بالإنجليزية.
التباين
56 زوجًا لونيًا فُحص · جميعها تجتاز WCAG 2.1 AAعرض 14 حالةإخفاء
| النمط / الحالة | الفاتح | الداكن |
|---|---|---|
| off / track | 4.57:1 3:1 | 3.80:1 3:1 |
| on / track | 4.54:1 3:1 | 3.68:1 3:1 |
| on / track, hovered | 8.18:1 3:1 | 3.68:1 3:1 |
| on / track, pressed | 10.34:1 3:1 | 3.68:1 3:1 |
| focus ring | 17.31:1 3:1 | 17.49:1 3:1 |
| border, error | 4.62:1 3:1 | 4.65:1 3:1 |
| border, read-only | 4.57:1 3:1 | 3.80:1 3:1 |
| off / thumb | 4.77:1 3:1 | 4.59:1 3:1 |
| on / thumb | 4.74:1 3:1 | 4.74:1 3:1 |
| on / thumb, hovered | 8.55:1 3:1 | 4.74:1 3:1 |
| on / thumb, pressed | 10.81:1 3:1 | 4.74:1 3:1 |
| on / check icon | 4.74:1 3:1 | 4.74:1 3:1 |
| label | 14.53:1 AAA | 15.87:1 AAA |
| helper text | 4.77:1 AA | 6.32:1 AA |
يحتاج النص إلى تباين 4.5:1، والأيقونات وحلقات التركيز إلى 3:1. الحالات المعطّلة مستثناة. تقرير التباين الكامل