مجموعة أزرار التبديل
خيارات مترابطة في صف واحد متصل، يُختار منها واحد: لتبديل طريقة العرض أو تصفية النتائج. الخيار الأول في بداية السطر، أي على اليمين في العربية.
فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:
المعاينة
«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.
التثبيت
أضف المكوّن
npx ritla add toggle-groupويعمل أيضًا مع shadcn:
npx shadcn@latest add @ritla/toggle-groupالاعتماديات التي يضيفها
@base-ui/react@phosphor-icons/reactأو انسخه يدويًا
التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.
الاستخدام
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";<ToggleGroup aria-label="Period" defaultValue="week"> <ToggleGroupItem value="day" label="Day" /> <ToggleGroupItem value="week" label="Week" /> <ToggleGroupItem value="month" label="Month" /></ToggleGroup>أمثلة
الأنماط
outline (الافتراضي) وtonal وfilled. الخيار المختار يأخذ لون الزر المضغوط، والفواصل والإطار بلون واحد. الخيار المعطّل يبقى ظاهرًا.
الأحجام
بارتفاعات الزر: 56 و48 و40 و32 بكسل. مساحة النقر 48 بكسل على الأقل في sm وxs.
أيقونات فقط
showLabel={false} يُبقي الأيقونة وحدها لأشرطة الأدوات المدمجة، ويبقى label اسمًا لقارئات الشاشة.
تصفية ولوحة المفاتيح
نسخة متحكَّم بها عبر value وonValueChange، والأعداد تتبع إعداد الأرقام. Tab يدخل المجموعة مرة واحدة، والأسهم تنتقل بين الخيارات: في العربية السهم الأيسر هو التالي.
مرجع الخصائص
ToggleGroup
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
variant | "outline" | "tonal" | "filled" | "outline" | خاصية Style. |
size | "lg" | "md" | "sm" | "xs" | "lg" | خاصية Size: 56 و48 و40 و32 بكسل. |
value | string | لا يوجد | قيمة الخيار المختار (متحكَّم به). |
defaultValue | string | لا يوجد | الخيار المختار في البداية. في Figma هو الأول. |
onValueChange | (value: string) => void | لا يوجد | يُستدعى بالقيمة الجديدة. الضغط على المختار مجددًا لا يلغي اختياره. |
disabled | boolean | false | يعطّل كل الخيارات. |
aria-label | string | لا يوجد | اسم المجموعة («الفترة»، «طريقة العرض»). |
ToggleGroupItem
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
value | string | لا يوجد | معرّف الخيار. |
label | string | لا يوجد | مطلوب. خاصية Label، واسم الخيار حتى لو أُخفي النص. |
showLabel | boolean | true | خاصية Show Label. |
iconLeading | IconComponent | لا يوجد | Icon leading: أيقونة قبل النص. |
disabled | boolean | false | State = Disabled لهذا الخيار. |
إمكانية الوصول
لوحة المفاتيح
المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.
| المفتاح | ما يفعله |
|---|---|
| Tab | يدخل المجموعة مرة واحدة، على الخيار المختار، ويخرج منها بالضغطة التالية. |
| ArrowRightArrowLeft | ينتقل إلى الخيار التالي أو السابق ويلتف عند الطرفين. في العربية ينعكس الاتجاه. |
| EnterSpace | يختار الخيار الذي عليه التركيز. |
ARIA
- مجموعة
role="group"باسم منaria-label، وكل خيار زر أصلي يحملaria-pressed. - الاختيار لا يعتمد على اللون وحده: يعلنه
aria-pressed، ويبقى خيار واحد مختارًا دائمًا. - في وضع الأيقونات فقط يصبح
labelقيمةaria-labelللخيار.
ملاحظات العربية والاتجاه
ينعكس
- ترتيب الخيارات ينعكس: الأول في بداية السطر (اليمين في العربية)، والفواصل حدود منطقية تتبع الاتجاه.
- الأسهم تتبع اتجاه القراءة: السهم الأيسر ينتقل إلى الخيار التالي في العربية.
لا ينعكس
- الأيقونات غير الاتجاهية (قائمة، شبكة، خريطة) لا تنعكس؛ الاتجاهية فقط تنعكس عبر
<Icon>.
- الأرقام
- الأعداد داخل الخيارات («مفتوحة 12») تُنسّق بـ
formatNumberوتتبع إعداد الأرقام. - الخط العربي
body-16(وbody-14فيxs) بوزن Semibold كالزر. الخيارات تأخذ عرض نصها، فالعربية الأقصر لا تُمدّ.- النص ثنائي الاتجاه
- اسم لاتيني داخل خيار عربي («عرض Kanban») يُعرض صحيحًا في نهاية النص؛ في وسطه ضعه في
<bdi>.
الفحوص التي يجتازها
فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.