مؤشر الخطوات (Steps)

يبيّن موقع المستخدم في عملية من عدة خطوات: ما اكتمل منها، والخطوة الحالية، وما بقي.

التثبيت

bash

npx @smicolon/fasla-ui@latest add steps

قبل إضافة أي مكوّن، شغّل الأمر init مرة واحدة في مشروعك. التفاصيل في صفحة التثبيت.

معاينة

السلة, completed، مكتملة
الشحن
الدفع, not started، لم تبدأ

الأنماط (variant)

شكلان للرمز: مربع أو دائري.

قياسي

السلة, completed، مكتملة
الشحن
الدفع, not started، لم تبدأ

مستدير

السلة, completed، مكتملة
الشحن
الدفع, not started، لم تبدأ

التوجيه

تصطف الخطوات في صف، أو في عمود حين تكثر الخطوات أو تطول تسمياتها.

قياسي

السلة, completed، مكتملة
الشحن
الدفع, not started، لم تبدأ

مستدير

السلة, completed، مكتملة
الشحن
الدفع, not started، لم تبدأ

الأيقونة والوصف

يمكن أن تعرض الخطوة المكتملة علامة الصح بدل رقمها، ويمكن أن يكون لأي خطوة وصف.

السلة, completed، مكتملة3 منتجات
الشحنالعنوانالعنوان وطريقة التوصيل
الدفع, not started، لم تبدأبالبطاقةبطاقة أو محفظة

السلة, completed، مكتملة3 منتجات
الشحنالعنوان وطريقة التوصيل
الدفع, not started، لم تبدأبطاقة أو محفظة

إتاحة الوصول (accessibility)

المكوّن Steps قائمة مرتّبة، فيُعلن قارئ الشاشة عدد الخطوات وموضع كل خطوة منها.
تحمل الخطوة الحالية السمة aria-current="step"، فيُعلن قارئ الشاشة أنها الحالية.
تُعلن الخطوات المكتملة والقادمة حالتها بعد التسمية، «مكتملة» أو «لم تبدأ»، بلغة الصفحة. وتغيّرها الخاصية statusLabel.
الخطوات تعرض التقدّم فقط، فلا رابط فيها ولا زر، ولا ينتقل إليها التركيز بمفتاح Tab.
يتبع الاتجاه السمة dir في الصفحة، ولا توجد له خاصية. في الصفحات من اليمين إلى اليسار تقع الخطوة الأولى على اليمين. وتبقى الأرقام لاتينية.

الخصائص (props)

`Steps`

الخاصية	النوع	الافتراضي	الوصف
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	صف تقع فيه التسميات تحت الرموز، أو عمود تقع فيه بجانبها.
`radius`	`"standard" \| "rounded"`	`"standard"`	شكل الرمز في كل الخطوات: مربع بزوايا 8px أو دائرة.
`aria-label`	`string`	لا يوجد	الاسم الذي يقرؤه قارئ الشاشة للقائمة، مثل اسم العملية.
`children`	`ReactNode`	لا يوجد	الخطوات بالترتيب، وكل منها `StepsItem`. تُرقّم كل خطوة، ويُرسم فاصل التقدّم بعد كل خطوة إلا الأخيرة.
`className`	`string`	لا يوجد	أصناف إضافية للقائمة.

`StepsItem`

الخاصية	النوع	الافتراضي	الوصف
`status`	`"done" \| "current" \| "upcoming"`	`"upcoming"`	حالة الخطوة: مكتملة أو حالية أو قادمة. تحدّد لون الرمز وفاصل التقدّم، وتضع السمة `aria-current` على الخطوة الحالية.
`label`	`ReactNode`	لا يوجد	اسم الخطوة.
`description`	`ReactNode`	لا يوجد	سطر نص تحت التسمية.
`icon`	`boolean`	`false`	تعرض علامة الصح بدل الرقم، وهي للخطوات المكتملة.
`statusLabel`	`string`	لا يوجد	ما يقرؤه قارئ الشاشة بعد التسمية. الافتراضي «مكتملة» أو «لم تبدأ» بلغة الصفحة، والقيمة `""` توقفه.
`className`	`string`	لا يوجد	أصناف إضافية للخطوة.

الاستخدام

خطوات إتمام الشراء

tsx

import { Steps, StepsItem } from "@/components/ui/steps"

export function CheckoutSteps() {
  return (
    <Steps aria-label="إتمام الشراء">
      <StepsItem status="done" label="السلة" />
      <StepsItem status="done" label="الشحن" />
      <StepsItem status="current" label="الدفع" />
      <StepsItem status="upcoming" label="المراجعة" />
    </Steps>
  )
}

الحالات من الخطوة الحالية

tsx

import { Steps, StepsItem } from "@/components/ui/steps"

const steps = ["السلة", "الشحن", "الدفع", "المراجعة"]

export function CheckoutProgress({ current }: { current: number }) {
  return (
    <Steps aria-label="إتمام الشراء" radius="rounded">
      {steps.map((label, index) => (
        <StepsItem
          key={label}
          label={label}
          status={index < current ? "done" : index === current ? "current" : "upcoming"}
          icon={index < current}
        />
      ))}
    </Steps>
  )
}

عمودي مع وصف

tsx

import { Steps, StepsItem } from "@/components/ui/steps"

export function OrderSteps() {
  return (
    <Steps aria-label="إتمام الشراء" orientation="vertical">
      <StepsItem status="done" label="السلة" description="3 منتجات" />
      <StepsItem status="done" label="الشحن" description="العنوان وطريقة التوصيل" />
      <StepsItem status="current" label="الدفع" description="بطاقة أو محفظة" />
      <StepsItem status="upcoming" label="المراجعة" description="راجع طلبك" />
    </Steps>
  )
}