مفتاح التبديل
يشغّل إعدادًا واحدًا أو يوقفه، ويُطبَّق التغيير فورًا. المقبض في بداية السطر حين يكون متوقفًا، وينتقل إلى نهايته عند التشغيل.
فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:
المعاينة
«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.
التثبيت
أضف المكوّن
npx ritla add switchويعمل أيضًا مع shadcn:
npx shadcn@latest add @ritla/switchالاعتماديات التي يضيفها
@base-ui/react@phosphor-icons/reactأو انسخه يدويًا
التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.
الاستخدام
import { Switch } from "@/components/ui/switch";<Switch name="alerts" defaultChecked description="Notify me when a price moves 5%"> Price alerts</Switch>أمثلة
الحالات والمقاس والأيقونة
icon يضع علامة صح أو X في المقبض، وsize="sm" المفتاح الصغير، وdisabled يعطّله، وlabel يضع تسمية فوق الصف ويجعله مجموعة مسمّاة.
صف إعداد بعنوان ووصف
SwitchRow مفتاح بعنوان ووصف لصفوف الإعدادات، يملأ العرض: عنوان body-16 فوق body-14 على بعد 12 بكسل من المفتاح، وsize="sm" عنوان body-14 فوق body-12 على بعد 8 بكسل. كان اسمه في Figma «Toggle»؛ زر التبديل الذي يبقى مضغوطًا هو Toggle.
صف الإعداد: المقاس الصغير والتعطيل
disabled يعطّل المفتاح والنصوص.
قائمة إعدادات بفواصل
placement="end" يضع النص في البداية والمفتاح عند النهاية، وdivided يضيف خطًا رفيعًا تحت كل صف و16 بكسل فوقه وتحته. في العربية تصطف المفاتيح على اليسار، و«تشغيل» يحرّك المقبض نحو النهاية، أي إلى اليسار.
مرجع الخصائص
Switch
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
children | ReactNode | لا يوجد | خاصية Label: اسم الإعداد، لا حالته. |
checked / defaultChecked | boolean | لا يوجد | خاصية Value: On أو Off. |
onCheckedChange | (checked: boolean) => void | لا يوجد | عند التبديل. |
description | ReactNode | لا يوجد | خاصية Show hint support: سطر مساعد. |
label | ReactNode | لا يوجد | خاصية Show label: تسمية فوق الصف. |
size | "md" | "sm" | "md" | المسار 52×32 أو 32×20. |
icon | boolean | false | خاصية Icon: صح عند التشغيل وX عند الإيقاف. |
disabled | boolean | لا يوجد | State = Disabled. |
name / value | string | لا يوجد | للنماذج: تُرسل القيمة وهو مفعّل. |
SwitchRow
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
children | ReactNode | لا يوجد | خاصية Title. |
description | ReactNode | لا يوجد | خاصية Description. |
checked / defaultChecked / onCheckedChange | … | لا يوجد | خاصية Value، كما في Switch. |
size | "md" | "sm" | "md" | خاصية Size. |
placement | "start" | "end" | "start" | موضع المفتاح: قبل النص (start) أو عند نهاية الصف (end) لقوائم الإعدادات. |
divided | boolean | false | خط رفيع تحت الصف و16 بكسل فوقه وتحته، لقائمة بفواصل. |
icon / disabled / name / value | … | لا يوجد | كما في Switch. |
SwitchCore
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
aria-label / aria-labelledby | string | لا يوجد | المسار والمقبض وحدهما لبناء صفوف خاصة؛ سمِّه. |
إرشادات الاستخدام
مفتاح التبديل يشغّل إعدادًا أو يوقفه فورًا. هنا: متى تختاره بدل مربع التفعيل، وكيف تسمّيه، وما يحدث حين يتأخر التغيير أو يفشل، وما تتحقق منه قبل التسليم.
1. مفتاح تبديل أم مربع تفعيل
استخدم مفتاح التبديل حين يغيّر تبديله شيئًا فورًا: الإشعارات، أو إعداد خصوصية، أو الوضع الداكن. وإن كان الاختيار ينتظر زر «حفظ» أو «إرسال» فهو مربع تفعيل. والخياران المسمّيان المتقابلان («شهري» أو «سنوي») اختيار بين خيارات، لا تشغيل وإيقاف.
| تحتاج إلى | استخدم | السبب |
|---|---|---|
| تشغيل إعداد أو إيقافه، يُطبَّق فورًا | مفتاح التبديل | الموضع يبيّن الحالة الحالية، والضغط يغيّرها. |
| صف إعدادات بعنوان ووصف | بطاقة الإعداد | مساحة للشرح، والصف كله هدف الضغط. |
| الاشتراك في شيء يُحفظ مع نموذج | مربع التفعيل | لا يحدث شيء حتى يُرسل النموذج. |
| الاختيار بين خيارين مسمّيين («شهري»، «سنوي») | مجموعة أزرار التبديل أو أزرار الاختيار | لكلا الخيارين اسم، وليس أحدهما «إيقافًا». |
المفاتيح تُطبَّق فورًا
قبول الشروط في آخر نموذج إنشاء حساب.
2. سمِّ الإعداد لا الحالة
التسمية تسمّي ما يتحكم فيه المفتاح، والمفتاح نفسه يبيّن هل هو مشغّل. وكلمات مثل «تشغيل» أو «إيقاف» أو «تفعيل» في التسمية إما تكرر المفتاح وإما تناقضه بعد الضغط.
سمِّ ما يتحكم فيه
إعداد للإشعارات.
افعل
- سمِّ الإعداد: «تنبيهات الأسعار»، «التحقق بخطوتين».
- أضف سطرًا مساعدًا حين لا يكون الأثر واضحًا.
- اجعل التسميات قصيرة تتسع في سطر واحد على الجوال.
تجنّب
- كتابة الحالة في التسمية: «الإشعارات مشغّلة».
- البدء بفعل يقلب المعنى: «تعطيل التنبيهات».
- وضع سؤال في التسمية: «تلقّي التنبيهات؟».
3. حين يتأخر التغيير أو يفشل
معظم المفاتيح تُطبَّق فورًا. وحين يذهب التغيير إلى الخادم، بدّل المفتاح فورًا وأرجعه إن فشل الطلب، مع رسالة تقول ذلك. وحين يكون للإيقاف عواقب (التحقق بخطوتين، المشاركة)، اطلب التأكيد أولًا ثم غيّر المفتاح.
افعل
- بدّل فورًا، وأرجع واشرح إن فشل التغيير.
- أكّد التغييرات التي تُضعف الأمان أو تحذف بيانات قبل التبديل.
- أبقِ المفتاح قابلًا للاستخدام أثناء الحفظ؛ لا تعطّله دون سبب.
تجنّب
- إبقاء المفتاح مشغّلًا بعد فشل التغيير.
- إضافة زر «حفظ» إلى شاشة من المفاتيح.
- عرض مؤشر تحميل مكان المفتاح للتغييرات السريعة.
4. قوائم الإعدادات
في قائمة إعدادات، كل صف بطاقة إعداد: عنوان، ووصف اختياري، والمفتاح عند نهاية السطر. والصف كله يبدّل المفتاح. اجمع الصفوف المترابطة تحت عناوين أقسام، وأبقِ المفاتيح في عمود واحد كي تُقرأ حالاتها بنظرة.
افعل
- ضع المفتاح عند نهاية سطر كل صف، في عمود واحد.
- اجعل الصف كله يبدّل المفتاح.
- اشرح ما يفعله الإعداد في الوصف حين لا يستطيع العنوان.
تجنّب
- خلط المفاتيح ومربعات التفعيل في قائمة إعدادات واحدة.
- وضع المفتاح بعد النص مباشرة، فيتعرّج العمود.
- وضع روابط أو أزرار داخل صف المفتاح.
5. العربية والاتجاه من اليمين إلى اليسار
في حالة الإيقاف يبقى المقبض في بداية السطر، وفي حالة التشغيل ينتقل إلى نهايته. وفي العربية يعني ذلك أن التشغيل هو المقبض على اليسار. والنسخة العربية تفعل ذلك عنك، وفي الكود يتبع المفتاح اتجاه الصفحة. لا تقلبه يدويًا، ولا تعكس أيقونتي الصح والإكس داخل المقبض.
التشغيل ينتقل نحو نهاية السطر
تنبيهات الأسعار مشغّلة، بالعربية.
قبل التسليم
- كل مفتاح يُطبَّق فورًا، وخيارات النماذج مربعات تفعيل.
- التسميات تسمّي الإعداد لا الحالة.
- سلوك الفشل والتأكيد مدوّن للإعدادات الحساسة.
- الشاشات العربية تستخدم النسخ العربية، والمفاتيح عند نهاية السطر.
إمكانية الوصول
لوحة المفاتيح
المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.
| المفتاح | ما يفعله |
|---|---|
| Space | يبدّل الحالة. |
| Enter | يبدّل الحالة أيضًا. |
ARIA
role="switch"معaria-checked، مسمّى بنص الصف ومرتبط بسطره المساعد؛ النقر على النص يبدّله.- مساحة اللمس 48 بكسل على الأقل حتى في المقاس الصغير.
- داخل نموذج له زر إرسال استخدم مربع التفعيل.
افعل
- تسمية ظاهرة لكل مفتاح.
- Space يبدّل، والصف كله قابل للنقر.
- أظهر الحالة بالموضع لا باللون وحده؛ خيار الأيقونة يضيف علامة صح وعلامة X.
- أبقِ المقبض ظاهرًا في حالة الإيقاف بتباين 3:1.
تجنّب
- مفتاح بلا تسمية، أو بأيقونة وحدها.
- تغيير إعدادات أخرى في الصفحة دون إعلان ذلك.
ملاحظات العربية والاتجاه
ينعكس
- المفتاح في بداية الصف (اليمين).
- التشغيل يحرك المقبض إلى نهاية السطر: إلى اليسار في العربية. لا تعكسه يدويًا.
لا ينعكس
- علامة الصح وX داخل المقبض لا تنعكسان.
- الأرقام
- الأرقام في النصوص تتبع
numeralsعبرformatNumber. - الخط العربي
- النص
label-16بوزن Medium، والسطر المساعدlabel-12؛ الصف يطول مع ارتفاع السطر العربي.
افعل
- النسخة العربية: في حالة التشغيل يكون المقبض على اليسار.
- المفتاح في نهاية السطر العربي، أي اليسار.
- علامتا الصح وX داخل المقبض كما هما.
تجنّب
- النسخة الإنجليزية في صف عربي، فيبدو التشغيل إيقافًا.
- تبديل التشغيل والإيقاف يدويًا «لإصلاح» الاتجاه.
الفحوص التي يجتازها
فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.