مربع التفعيل
لاختيار أي عدد من الخيارات، أو لتفعيل إعداد قبل الإرسال. المربع في بداية السطر، والتسمية تبدّله أيضًا.
فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:
المعاينة
«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.
التثبيت
أضف المكوّن
npx ritla add checkboxويعمل أيضًا مع shadcn:
npx shadcn@latest add @ritla/checkboxالاعتماديات التي يضيفها
@base-ui/react@phosphor-icons/reactأو انسخه يدويًا
التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.
الاستخدام
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" هو المربع الكبير للمس بهالته.
مرجع الخصائص
Checkbox
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
children | ReactNode | لا يوجد | خاصية Label. بصيغة إيجابية («أرسل لي التحديثات»). |
description | ReactNode | لا يوجد | خاصية Show hint support: سطر مساعد. |
checked / defaultChecked | boolean | لا يوجد | خاصية Value. |
onCheckedChange | (checked: boolean) => void | لا يوجد | عند التبديل. |
indeterminate | boolean | false | Value = Indeterminate (aria-checked="mixed"). |
error | ReactNode | boolean | لا يوجد | State = Error: الرسالة تحلّ محل الوصف. |
disabled / readOnly / required | boolean | لا يوجد | 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؛ ارتفاع السطر العربي أطول ويبقى المربع في أول سطر.
افعل
- النسخة العربية، والمربع على اليمين.
- علامة الصح كما هي، فهي ليست اتجاهية.
تجنّب
- نص عربي في النسخة الإنجليزية.
- عكس علامة الصح.
الفحوص التي يجتازها
فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.