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

مربع التفعيل

احصل على Ritla UI

لاختيار أي عدد من الخيارات، أو لتفعيل إعداد قبل الإرسال. المربع في بداية السطر، والتسمية تبدّله أيضًا.

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

افتح في Figma

المعاينة

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

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

التثبيت

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

    npx ritla add checkbox

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

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

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

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

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

الاستخدام

checkbox.tsx
import { Checkbox } from "@/components/ui/checkbox";<Checkbox name="updates" description="About once a month.">Send me product updates</Checkbox>

أمثلة

القيم والحالات

checked وindeterminate (بعض الأبناء فقط)، وerror وdisabled وreadOnly. ‏size="lg" هو المربع الكبير للمس بهالته.

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

مرجع الخصائص

Checkbox

الخاصيةالنوعالافتراضيالوصف
childrenReactNodeلا يوجدخاصية Label. بصيغة إيجابية («أرسل لي التحديثات»).
descriptionReactNodeلا يوجدخاصية Show hint support: سطر مساعد.
checked / defaultCheckedbooleanلا يوجدخاصية Value.
onCheckedChange(checked: boolean) => voidلا يوجدعند التبديل.
indeterminatebooleanfalseValue = Indeterminate ‏(aria-checked="mixed").
errorReactNode | booleanلا يوجدState = Error: الرسالة تحلّ محل الوصف.
disabled / readOnly / requiredbooleanلا يوجدState = Disabled وRead-only.
size"sm" | "lg""sm"‏Small (Web) مربع 18px، أو Large (Native) مربع 20px بهالة في مساحة 48px.
name / value / parent…لا يوجدللنماذج ولـCheckboxGroup (‏parent لخيار «الكل»).

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

مربع التفعيل خيار مستقل يُفعَّل أو يُلغى ويُحفظ مع النموذج. هنا: متى تختاره، وكيف تكتب تسميته، وكيف تجمع المربعات، وما تتحقق منه قبل التسليم.

1. مربع تفعيل أم عنصر آخر

استخدم مربع التفعيل حين يكون كل خيار مستقلًا بذاته ويُطبَّق الاختيار عند الإرسال. وإن كان خيار واحد فقط يمكن أن يصح، أو يجب أن يُطبَّق التغيير فورًا، فعنصر آخر أنسب.

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

2. اكتب التسمية

التسمية جملة مثبتة تصح حين يُفعَّل المربع: «أرسل إليّ كشف الحساب الشهري بالبريد». والتسمية كلها تبدّل المربع، لا المربع وحده. ومربعات الموافقة والتسويق تبدأ غير مفعّلة دائمًا، فيقرر الشخص بنفسه.

قلها بصيغة مثبتة، ودع الناس يختارون

الاشتراك في العروض عند إنشاء حساب.

افعل: مثبتة وغير مفعّلةيفعّل الناس المربع إن أرادوا العروض، والمعنى واضح.
تجنّب: منفية ومفعّلةإلغاء «لا ترسل إليّ» لتلقّي الرسائل نفي مزدوج، والمربع حُسم نيابة عنهم.

افعل

  • اكتب ما يعنيه تفعيل المربع: «أرسل إليّ العروض».
  • اجعل التسمية سطرًا واحدًا، وضع التفاصيل في النص المساعد.
  • ابدأ مربعات الموافقة والتسويق غير مفعّلة.
  • اربط الشروط الطويلة من التسمية: «أوافق على الشروط».

تجنّب

  • كتابة النفي: «لا ترسل إليّ العروض».
  • تفعيل الموافقة على التسويق أو مشاركة البيانات مسبقًا.
  • وضع سؤال في التسمية («تلقّي الرسائل؟»).

3. المجموعات و«تحديد الكل»

ضع المربعات المترابطة تحت تسمية واحدة في مجموعة مربعات التفعيل (fieldset مع legend في الكود). رتّبها ترتيبًا منطقيًا، واجعلها نحو عشرة على الأكثر. ويصبح مربع «تحديد الكل» في الحالة غير المحددة حين يُفعَّل بعض الفروع فقط.

مجموعة مسمّاة ومتراصة

تفضيلات الإشعارات.

افعل: مجموعة بتسميةتسمية واحدة تسمّي المجموعة، وكل خيار مستقل بذاته.
تجنّب: مربعات متفرقةدون تسمية للمجموعة، لا يتضح عمّ تتحدث الخيارات.

افعل

  • أعطِ المجموعة تسمية تقول ما الخيارات.
  • رتّب الخيارات عموديًا، خيارًا في كل سطر.
  • استخدم مربع «تحديد الكل» للقوائم الطويلة؛ الكود يضبط الحالة غير المحددة.
  • ضع خطأ المجموعة أو تلميحها تحت المجموعة كلها.

تجنّب

  • وضع المربعات جنبًا إلى جنب في صف، فيصعب تصفحها.
  • أكثر من عشرة خيارات تقريبًا؛ استخدم القائمة المنسدلة متعددة الاختيار.
  • عرض الحالة غير المحددة على مربع بلا فروع.

4. بطاقات الاختيار

بطاقة الاختيار صف قائمة أو بطاقة تُختار بمربع تفعيل، للخيارات التي تحتاج إلى أكثر من تسمية: وصف أو سعر أو أيقونة أو صورة رمزية. والبطاقة كلها هي التسمية. ويقع المربع عند نهاية السطر، أو في بدايته مع Leading type = Checkbox.

افعل

  • استخدم البطاقات حين تختلف الخيارات في تفاصيل يحتاج الناس إلى مقارنتها.
  • اجعل العنوان قصيرًا وضع التفاصيل في النص المساعد.
  • اعرض السعر أو الكمية نصًا في النهاية.

تجنّب

  • وضع أزرار أو روابط داخل بطاقة الاختيار.
  • خلط بطاقات الاختيار ومربعات التفعيل العادية في مجموعة واحدة.

5. الأخطاء والمربعات المطلوبة

حين يجب تفعيل مربع للمتابعة، مثل قبول الشروط، قل ذلك في رسالة الخطأ عند الإرسال، تحت المربع. والمجموعة في حالة الخطأ تعرض كل مربع في الخطأ ورسالة واحدة للمجموعة.

قل ما المطلوب

مربع الشروط بعد إرسال فاشل.

افعل: خطأ مع رسالةالرسالة تقول بالضبط ما الناقص.
تجنّب: حالة الخطأ وحدهامربع أحمر وحده لا يقول لماذا توقف النموذج.

افعل

  • قل ما العمل: «اقبل الشروط للمتابعة».
  • اعرض الخطأ عند الإرسال، لا والناس ما زالوا يقرأون.

تجنّب

  • عرض حالة الخطأ دون رسالة.
  • تعطيل زر الإرسال حتى يُفعَّل المربع، دون شرح.

6. العربية والاتجاه من اليمين إلى اليسار

في الشاشات العربية استخدم النسخة العربية: يقع المربع في بداية السطر (اليمين) وتمتد التسمية إلى يساره. وعلامة الصح وشرطة الحالة غير المحددة لا تنعكسان أبدًا. واكتب التسميات بالعربية بلغتها وبصيغة مثبتة أيضًا.

المربع في بداية السطر

اشتراك في نموذج عربي.

افعل: النسخة العربيةالمربع على اليمين، حيث يبدأ السطر العربي.
تجنّب: النسخة الإنجليزية بنص عربيينتهي المربع بعد النص، على اليسار.

قبل التسليم

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

إمكانية الوصول

لوحة المفاتيح

المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.

المفتاحما يفعله
Spaceيبدّل المربع.

ARIA

  • role="checkbox" مع aria-checked ‏(true وfalse وmixed)، مسمّى بنصه ومرتبط بوصفه.
  • السطر كله <label>: النقر على النص يبدّله، ومساحة اللمس 48px على الأقل.
  • الخطأ يضع aria-invalid ويظهر السبب.

افعل

  • التسمية بجانب المربع وقابلة للنقر: الصف كله هدف اللمس.
  • Space يبدّل، وTab ينتقل.
  • الحالة غير المحسومة تُعلَن «مختلطة» (aria-checked="mixed"، يضبطها الكود).
  • هدف لمس بحجم 48 بكسل على شاشات اللمس (المقاس lg في التطبيقات).

تجنّب

  • إخفاء التسمية والاعتماد على نص قريب.
  • مربع اختيار ينفّذ إجراءً فورًا.

ملاحظات العربية والاتجاه

ينعكس

  • المربع في بداية السطر (اليمين) والنص بعده.

لا ينعكس

  • علامة الاختيار والشرطة لا تنعكسان.
الأرقام
لا أرقام في المربع.
الخط العربي
النص label-16 بوزن Medium، والوصف label-12؛ ارتفاع السطر العربي أطول ويبقى المربع في أول سطر.

افعل

  • النسخة العربية، والمربع على اليمين.
  • علامة الصح كما هي، فهي ليست اتجاهية.

تجنّب

  • نص عربي في النسخة الإنجليزية.
  • عكس علامة الصح.

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

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

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