انتقل إلى المحتوى

مفتاح التبديل

احصل على Ritla UI

يشغّل إعدادًا واحدًا أو يوقفه، ويُطبَّق التغيير فورًا. المقبض في بداية السطر حين يكون متوقفًا، وينتقل إلى نهايته عند التشغيل.

فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:

افتح في Figma

المعاينة

«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.

المعاينةالكود
إنجليزيمعكوسعربي
← RTL

التثبيت

  1. أضف المكوّن

    npx ritla add switch

    ويعمل أيضًا مع shadcn: npx shadcn@latest add @ritla/switch

  2. الاعتماديات التي يضيفها

    @base-ui/react@phosphor-icons/react

  3. أو انسخه يدويًا

    التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.

الاستخدام

switch.tsx
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 يضع تسمية فوق الصف ويجعله مجموعة مسمّاة.

إنجليزيمعكوسعربي
← RTL

صف إعداد بعنوان ووصف

SwitchRow مفتاح بعنوان ووصف لصفوف الإعدادات، يملأ العرض: عنوان body-16 فوق body-14 على بعد 12 بكسل من المفتاح، وsize="sm" عنوان body-14 فوق body-12 على بعد 8 بكسل. كان اسمه في Figma «Toggle»؛ زر التبديل الذي يبقى مضغوطًا هو Toggle.

إنجليزيمعكوسعربي
← RTL

صف الإعداد: المقاس الصغير والتعطيل

disabled يعطّل المفتاح والنصوص.

إنجليزيمعكوسعربي
← RTL

قائمة إعدادات بفواصل

placement="end" يضع النص في البداية والمفتاح عند النهاية، وdivided يضيف خطًا رفيعًا تحت كل صف و16 بكسل فوقه وتحته. في العربية تصطف المفاتيح على اليسار، و«تشغيل» يحرّك المقبض نحو النهاية، أي إلى اليسار.

إنجليزيمعكوسعربي
← RTL

مرجع الخصائص

Switch

الخاصيةالنوعالافتراضيالوصف
childrenReactNodeلا يوجدخاصية Label: اسم الإعداد، لا حالته.
checked / defaultCheckedbooleanلا يوجدخاصية Value: ‏On أو Off.
onCheckedChange(checked: boolean) => voidلا يوجدعند التبديل.
descriptionReactNodeلا يوجدخاصية Show hint support: سطر مساعد.
labelReactNodeلا يوجدخاصية Show label: تسمية فوق الصف.
size"md" | "sm""md"المسار 52×32 أو 32×20.
iconbooleanfalseخاصية Icon: صح عند التشغيل وX عند الإيقاف.
disabledbooleanلا يوجدState = Disabled.
name / valuestringلا يوجدللنماذج: تُرسل القيمة وهو مفعّل.

SwitchRow

الخاصيةالنوعالافتراضيالوصف
childrenReactNodeلا يوجدخاصية Title.
descriptionReactNodeلا يوجدخاصية Description.
checked / defaultChecked / onCheckedChange…لا يوجدخاصية Value، كما في Switch.
size"md" | "sm""md"خاصية Size.
placement"start" | "end""start"موضع المفتاح: قبل النص (start) أو عند نهاية الصف (end) لقوائم الإعدادات.
dividedbooleanfalseخط رفيع تحت الصف و16 بكسل فوقه وتحته، لقائمة بفواصل.
icon / disabled / name / value…لا يوجدكما في Switch.

SwitchCore

الخاصيةالنوعالافتراضيالوصف
aria-label / aria-labelledbystringلا يوجدالمسار والمقبض وحدهما لبناء صفوف خاصة؛ سمِّه.

إرشادات الاستخدام

مفتاح التبديل يشغّل إعدادًا أو يوقفه فورًا. هنا: متى تختاره بدل مربع التفعيل، وكيف تسمّيه، وما يحدث حين يتأخر التغيير أو يفشل، وما تتحقق منه قبل التسليم.

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 داخل المقبض كما هما.

تجنّب

  • النسخة الإنجليزية في صف عربي، فيبدو التشغيل إيقافًا.
  • تبديل التشغيل والإيقاف يدويًا «لإصلاح» الاتجاه.

الفحوص التي يجتازها

فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.

  • R050نص عربي يسقط إلى خط غير الخط المعلن (مقيسًا، أو وفق الإعلان، أو لأن خط الويب فشل في التحميل)
  • R051تباعد حروف مطبَّق على نص عربي (يكسر الخط المتصل)
  • R042نص مقصوص: محتوى أعرض من صندوقه مع overflow مخفي وبلا علامة حذف
  • R043حاوية بعرض ثابت بالبكسل يتجاوز نصها العربي المساحة