التثبيت
npx sdaia-ui@latest add stepper
الاستخدام
import { Stepper } from '@/components/ui/Stepper';
import { StepperItem } from '@/components/ui/StepperItem';1<Stepper currentStep={2} aria-label="إنشاء مستخدم" labels={{ completed: "مكتملة", upcoming: "قادمة", error: "خطأ" }}>2<StepperItem title="الحساب" />3<StepperItem title="التفاصيل" />4<StepperItem title="المراجعة" />5<StepperItem title="تم" />6</Stepper>
أمثلة
الافتراضي
مؤشر خطوات أفقي فوق النموذج. تحدد الخاصية currentStep حالة كل خطوة من موضعها.
جارٍ تحميل العرض التوضيحي: stepper-default
عمودي
خطوات مكدّسة في عمود والنص بجانبها؛ يناسب اللوحة الجانبية.
جارٍ تحميل العرض التوضيحي: stepper-vertical
الحالات
مكتملة وحالية وقادمة وخطأ. يتحوّل الخط الواصل إلى الأخضر عند اكتمال الخطوة السابقة.
جارٍ تحميل العرض التوضيحي: stepper-statuses
خطأ في خطوة
ميّز الخطوة التي فيها مشكلة واذكر الخطأ في الوصف.
جارٍ تحميل العرض التوضيحي: stepper-error
سير الموافقة
استخدم الوصف لعرض المسؤول عن كل خطوة أو تاريخها.
جارٍ تحميل العرض التوضيحي: stepper-approval
العربية (من اليمين إلى اليسار)
ينعكس الترتيب والمحاذاة للقراءة من اليمين إلى اليسار.
جارٍ تحميل العرض التوضيحي: stepper-rtl
عمودي بالعربية
ينعكس المؤشر العمودي أيضاً: ينتقل المسار إلى اليمين.
جارٍ تحميل العرض التوضيحي: stepper-vertical-rtl
متى تستخدمه
استخدم مؤشر الخطوات لـ:
- النماذج متعددة الخطوات من ثلاث إلى ست خطوات
- سير الموافقات والتهيئة
- عرض التقدم في تسلسل ثابت
- إظهار ما تبقى للمستخدم
لا تستخدمه لـ:
- التنقل بين صفحات غير مترابطة: استخدم التبويبات
- عرض نسبة مئوية: استخدم شريط التقدم
- تخطيطات الهاتف: استخدم المؤشر الدائري للخطوات
- المسارات التي تزيد على سبع خطوات: اجمعها في مجموعات
أفضل الممارسات
- اجعل عناوين الخطوات كلمة أو كلمتين، مثل الحساب والتفاصيل والمراجعة.
- اختر الاتجاه حسب المساحة: الأفقي فوق النموذج، والعمودي في اللوحة الجانبية.
- عند وجود خطأ في خطوة استخدم حالة الخطأ واذكر المشكلة في الوصف، ولا تعلّمها مكتملة.
الخصائص
Stepper
الخاصية | النوع | القيمة الافتراضية | مطلوبة |
|---|---|---|---|
orientation | "horizontal" | "vertical" | "horizontal" | اختيارية |
currentStep | number | — | اختيارية |
children | StepperItem elements | — | اختيارية |
dir | "ltr" | "rtl" | — | اختيارية |
labels | { completed?: string; upcoming?: string; error?: string } | { completed: "Completed", upcoming: "Upcoming", error: "Error" } | اختيارية |
aria-label | string | — | اختيارية |
StepperItem
الخاصية | النوع | القيمة الافتراضية | مطلوبة |
|---|---|---|---|
title | ReactNode | — | مطلوبة |
description | ReactNode | — | اختيارية |
status | "completed" | "current" | "upcoming" | "error" | "upcoming" | اختيارية |
stepNumber | ReactNode | الموضع | اختيارية |
connector | boolean | true (false في الخطوة الأخيرة) | اختيارية |
orientation | "horizontal" | "vertical" | من Stepper | اختيارية |
labels | { completed?: string; upcoming?: string; error?: string } | من Stepper | اختيارية |
إمكانية الوصول
- مؤشر الخطوات قائمة مرتّبة (ol)؛ سمّها باستخدام aria-label.
- تحمل الخطوة الحالية aria-current="step"، وتضيف الخطوات المكتملة والقادمة وذات الخطأ حالتها نصاً مخفياً بصرياً فلا تعتمد على الأيقونة وحدها.
- المؤشرات والخطوط زخرفية ومخفية عن قارئ الشاشة.
- المكوّن غير تفاعلي ولا يضيف نقاط توقف لمفتاح Tab.
- تباين دوائر الخطوات والخطوط مع الصفحة 3:1 على الأقل في الوضعين الفاتح والداكن.
السلوك المتجاوب
- يملأ المؤشر الأفقي حاويته ويقسم الصف بالتساوي بين الخطوات.
- عندما تضيق الحاوية عن 560 بكسل يتحوّل المؤشر الأفقي إلى التخطيط العمودي حتى لا تتداخل العناوين. على الهاتف فكّر في المؤشر الدائري للخطوات.
- تتبع أحجام النصوص والمسافات والأيقونات الرموز المتجاوبة العامة.