مبدّل المحتوى
يبدّل فورًا بين خيارين إلى أربعة عروض أو مرشّحات للمحتوى نفسه، مثل يوم وأسبوع وشهر (وحتى ست فترات بشكل الكبسولات)؛ خيار واحد محدد دائمًا.
فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:
المعاينة
«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.
التثبيت
أضف المكوّن
npx ritla add content-switcherويعمل أيضًا مع shadcn:
npx shadcn@latest add @ritla/content-switcherالاعتماديات التي يضيفها
@base-ui/reactأو انسخه يدويًا
التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.
الاستخدام
import { ContentSwitcher, ContentSwitcherItem } from "@/components/ui/content-switcher";<ContentSwitcher aria-label="Period" defaultValue="day"> <ContentSwitcherItem value="day">Day</ContentSwitcherItem> <ContentSwitcherItem value="week">Week</ContentSwitcherItem> <ContentSwitcherItem value="month">Month</ContentSwitcherItem></ContentSwitcher>أمثلة
المقاسات
sm بارتفاع 32 (الافتراضي)، وmd بارتفاع 40، وlg بارتفاع 48.
عدّادات وأيقونات
عدد بعد التسمية، أو أيقونات وحدها مع إبقاء التسمية لقارئ الشاشة (showLabel={false}).
اللون المحايد
tone="neutral" يلوّن الخيار المحدد بلون السطح المعكوس، حين ينافس لون العلامة الإجراء الرئيسي في الصفحة.
الكبسولات
variant="pill-segmented" مسار رمادي فيه خيار مرتفع، وvariant="pills" كبسولات منفصلة. بالمقاس الصغير واللون المحايد فقط كما في Figma، وحتى ست فترات. اكتب الفترات بالعربية كلمات لا اختصارات لاتينية، ويمرَّر الصف جانبيًا إن لم يتسع.
مرجع الخصائص
ContentSwitcher
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
size | "sm" | "md" | "lg" | "sm" | خاصية Size: 32 أو 40 أو 48 بكسل. |
value / defaultValue | string | لا يوجد | الخيار المحدد (متحكَّم به أو أولي). في Figma يُحدَّد الأول. |
onValueChange | (value: string) => void | لا يوجد | يُستدعى عند اختيار خيار. |
dividers | boolean | true | خاصية Divider: خطوط بين الخيارات غير المحددة (الشكل الافتراضي فقط). |
tone | "brand" | "neutral" | "brand" | خاصية Tone. الكبسولات محايدة دائمًا. |
variant | "default" | "pill-segmented" | "pills" | "default" | خاصية Style. الكبسولات بالمقاس الصغير، فلا يُطبَّق size عليها. |
disabled | boolean | false | يعطّل كل الخيارات. |
aria-label | string | لا يوجد | اسم الاختيار لقارئ الشاشة («الفترة»). |
ContentSwitcherItem
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
value | string | لا يوجد | قيمة الخيار في المبدّل. |
children | ReactNode | لا يوجد | خاصية Label: كلمة واحدة قصيرة، وهي اسم الخيار حتى مع إخفائها. |
showLabel | boolean | true | خاصية Show label. عند إيقافها تبقى الأيقونة وحدها. |
iconLeading | IconComponent | لا يوجد | خاصية Icon: أيقونة 16 بكسل بلون التسمية. |
badge | number | string | لا يوجد | خاصية Badge وعددها: رمادية، وBrand على الخيار المحدد. |
disabled | boolean | false | State = Disabled لهذا الخيار. |
إرشادات الاستخدام
مبدّل المحتوى يغيّر طريقة عرض المحتوى الذي تحته مباشرة. هنا: متى تختاره، وكيف تكتب خياراته، وأي مقاس، وكيف يبدأ من اليمين في العربية، وما تتحقق منه قبل التسليم.
1. مبدّل المحتوى أم غيره
استخدم مبدّل المحتوى لتغيير طريقة عرض المحتوى الذي تحته مباشرة: رسم بياني حسب الفترة، أو قائمة حسب الحالة، أو خريطة أو قائمة. ويُطبَّق فورًا. واستخدمه داخل البطاقات والرسوم البيانية واللوحات، ومجموعة أزرار التبديل في أشرطة الأدوات بجوار الأزرار.
| تحتاج إلى | استخدم | السبب |
|---|---|---|
| تبديل رسم بياني أو بطاقة بين 2 و4 عروض | مبدّل المحتوى | خفيف ومدمج ويقع داخل المحتوى. |
| تبديل عرض في شريط أدوات، بجوار الأزرار | مجموعة أزرار التبديل | تطابق أنماط الأزرار ومقاساتها. |
| تقسيم صفحة إلى أقسام | التبويبات | للتبويبات لوحاتها، وتُقرأ بنيةً للصفحة. |
| اختيار خيار يُحفظ مع نموذج | مجموعة أزرار الاختيار | أزرار الاختيار تنتظر الإرسال. |
| الاختيار من أكثر من أربعة خيارات | القائمة المنسدلة أو التبويبات | يزدحم الصف المقسّم بعد أربعة. |
2. الخيارات والتسميات
من خيارين إلى أربعة، كلمة قصيرة لكل منها، بأطوال متقاربة لتبدو الأجزاء متساوية. والخيار الأول مختار افتراضيًا. والأيقونات اختيارية: على كل خيار أو على لا شيء. والخيارات ذات الأيقونة وحدها تحتفظ بتسميتها اسمًا لقارئات الشاشة.
خيارات قصيرة ومتساوية
مبدّل الفترة فوق رسم بياني للإنفاق.
افعل
- كلمة واحدة لكل خيار: «يوم»، «أسبوع»، «شهر»، «سنة».
- أبقِ التسميات بأطوال متقاربة.
- اجعل الخيار الأنفع أولًا ومختارًا.
تجنّب
- أكثر من أربعة خيارات.
- عبارة طويلة بين خيارات من كلمة واحدة.
- أيقونات على بعض الخيارات دون غيرها.
3. المقاس
المقاس sm (32) يناسب داخل البطاقات ورؤوس الرسوم البيانية، وmd (40) هو الافتراضي، وlg (48) يناسب الشاشات التي يكثر فيها اللمس. ويضيف sm وmd منطقة لمس غير مرئية بارتفاع 48 بكسل في الكود. طابِق ارتفاع العناصر المجاورة.
افعل
- استخدم
smفي رؤوس البطاقات والرسوم البيانية. - طابِق مقاس العناصر المجاورة.
تجنّب
- استخدام
lgفي رأس بطاقة كثيف. - مدّ المبدّل إلى العرض الكامل على الحاسوب.
4. العربية والاتجاه من اليمين إلى اليسار
تبدأ النسخة العربية من اليمين: الخيار الأول، المختار افتراضيًا، على اليمين، والأطراف المستديرة تتبع اتجاه القراءة. وتتبعه مفاتيح الأسهم أيضًا، فينتقل السهم الأيسر إلى الخيار التالي في العربية. وأبقِ ترتيب الخيارات كما في الإنجليزية.
الخيار الأول على اليمين
مبدّل الفترة بالعربية.
قبل التسليم
- من 2 إلى 4 خيارات تغيّر المحتوى الذي تحتها مباشرة.
- تسميات من كلمة بأطوال متقاربة؛ والأول مختار.
- المقاس يطابق ما يجاوره.
- الشاشات العربية تستخدم النسخة العربية.
إمكانية الوصول
لوحة المفاتيح
المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.
| المفتاح | ما يفعله |
|---|---|
| Tab | يدخل المبدّل مرة واحدة على الخيار المحدد، والضغطة التالية تغادره. |
| ArrowRightArrowLeft | ينقل التحديد إلى الخيار التالي أو السابق ويلتف عند الطرفين. في العربية ينعكس الاتجاه. |
| Space | يحدد الخيار الذي عليه التركيز. |
ARIA
-
role="radiogroup"باسم منaria-label، وكل خيارrole="radio"معaria-checked. - التحديد لا يعتمد على اللون وحده: الخيار المحدد ممتلئ بلون العلامة، والبقية بإطار.
- في الكبسولات المجزأة يأخذ الخيار المحدد حلقة
border/gray/strongرفيعة، لأن سطحه الأبيض 1.16:1 فقط أمام المسار. - للتنقل بين الصفحات استخدم التبويبات، وللإعدادات التي تُحفظ استخدم أزرار الاختيار.
افعل
- سمِّ المبدّل: «الفترة».
- Tab يدخل على الخيار المختار، والأسهم تنقل الاختيار وتتبع اتجاه القراءة.
- تسمية لكل خيار، حتى لو ظهرت أيقونته وحدها.
تجنّب
- استخدامه للانتقال إلى صفحات أخرى.
- الاعتماد على لون التعبئة وحده؛ فالخيار المختار له تسمية أقوى أيضًا.
ملاحظات العربية والاتجاه
ينعكس
- أول خيار على اليمين، والطرفان المستديران يتبعان الاتجاه.
- الأسهم معكوسة: ArrowLeft للتالي.
- الخط الفاصل على الحافة النهائية لكل خيار، أي يساره في العربية.
لا ينعكس
- أيقونات الرسوم البيانية والجداول تبقى كما هي.
- الأرقام
- عدد الشارة يتبع إعداد الأرقام.
- الخط العربي
-
label-14بوزن Medium بخط العرض، وارتفاع أدنى لا ثابت لأن أسطر العربية أطول. - النص ثنائي الاتجاه
- التسميات لا تنكسر على سطرين؛ اجعلها كلمة واحدة بطول متقارب.
افعل
- النسخة العربية، وأول خيار على اليمين.
- الترتيب نفسه كما في الإنجليزية، يسير من اليمين إلى اليسار.
- خيارات عربية من كلمة واحدة: «يوم» لا «يوم واحد».
تجنّب
- المبدّل الإنجليزي في شاشة عربية.
- عكس الخيارات يدويًا في النسخة الإنجليزية.
الفحوص التي يجتازها
فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.