مراحل (Stepper)

معرفی

کامپوننت‌های Stepper و Step برای نمایش مراحل یک فرایند چند مرحله‌ای استفاده می‌شوند. هر مرحله می‌تواند وضعیت «تکمیل‌شده»، «فعال»، «در انتظار» یا — با status="error" روی یک Step مشخص — «خطا» داشته باشد.

چه زمانی استفاده کنیم:

• برای فرآیندهای چندمرحله‌ای که ترتیب مشخصی دارند (مثل ثبت‌نام، خرید)
• وقتی کاربر باید پیشرفت خود را در مراحل ببیند
• برای فرم‌های طولانی که به چند مرحله تقسیم شده‌اند

چه زمانی استفاده نکنیم:

• برای navigation بین بخش‌های غیرترتیبی — از Tabs استفاده کنید
• برای فرآیندهای تک‌مرحله‌ای — از Dialog یا Form ساده استفاده کنید

زمین بازی

با تغییر تنظیمات زیر، پیش‌نمایش زنده را مشاهده کنید.

import { Stepper, Step } from '@partodata/ui'

<Stepper activeStep={1}>
  <Step label="انتخاب منبع" />
  <Step label="پیکربندی" />
  <Step label="بازبینی" />
  <Step label="اجرا" />
</Stepper>

استفاده

import { Stepper, Step } from '@partodata/ui'

export default function MyComponent() {
  return (
    <Stepper activeStep={1}>
      <Step label="اطلاعات پایه" description="نام و ایمیل" />
      <Step label="تأیید هویت" description="کد پیامکی" />
      <Step label="تکمیل پروفایل" />
    </Stepper>
  )
}

ظاهر

یک ظاهر در هر دو جهت، فقط با توکن‌ها:

• نشانگر مرحله دایره‌ای روی نردبان کوچک است: sm 20، md 24 و lg 30 پیکسل (lg هم‌قد کنترل sm)؛ شماره با نقش متنی caption (در lg، compact).
• مرحلهٔ فعال همان قاعدهٔ «انتخاب‌شده» کنترل‌های انتخاب (RadioCard، Checkbox) را دارد: حاشیهٔ رنگ متن روی زمینهٔ انتخاب، بدون حلقهٔ سبز. تکمیل‌شده سبز پر با تیک است، در انتظار سطح surface-200 با حاشیهٔ پیش‌فرض، و خطا قرمز پر.
• خط اتصال رنگ حاشیهٔ پیش‌فرض را دارد و بعد از یک مرحلهٔ تکمیل‌شده سبز کم‌رنگ می‌شود؛ در حالت افقی از وسط نشانگرها می‌گذرد.
• عنوان با نقش body (در sm، compact) و توضیح با caption در سطح کم‌رنگ‌تر متن. مرحلهٔ فعال aria-current="step" دارد.

حالت‌ها و انواع

عمودی

اندازه‌ها

وضعیت خطا

مرحله‌ای که اعتبارسنجی یا ثبت آن با شکست مواجه شده را با status="error" مشخص کنید — این مقدار، وضعیت محاسبه‌شده از روی activeStep را override می‌کند:

<Stepper activeStep={2}>
  <Step label="اطلاعات پایه" />
  <Step label="پرداخت" status="error" description="کارت رد شد" />
  <Step label="تکمیل سفارش" />
</Stepper>

Props

Stepper

Step

راهنمای استفاده

دسترسی‌پذیری

• از role="list" و role="listitem" استفاده می‌کند
• وضعیت هر مرحله از طریق aria-label اعلام می‌شود (تکمیل‌شده / فعال / در انتظار / خطا)

کامپوننت‌های مرتبط

• Tabs — وقتی بخش‌ها ترتیب مشخصی ندارند و کاربر باید آزادانه بین آن‌ها جابجا شود
• الگوهای فرم — راهنمای کامل ساخت فرم‌های چند مرحله‌ای با Stepper