Stepperv1.0.0
پیشرفت کاربر در یک فرآیند چندمرحله‌ای (مثل تسویه‌حساب یا فرم چندبخشی) را با شمارهٔ مرحله، خط رابط و سه وضعیت انجام‌شده/فعال/باقی‌مانده نشان می‌دهد؛ افقی یا عمودی.
این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نصب
با CLI اختصاصی digdesign کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.
npx digdesign@latest add https://docs.digdesign.ir/r/stepper.jsonpnpm dlx digdesign@latest add https://docs.digdesign.ir/r/stepper.jsonyarn dlx digdesign@latest add https://docs.digdesign.ir/r/stepper.jsonbunx --bun digdesign@latest add https://docs.digdesign.ir/r/stepper.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
استفاده
import { Stepper, StepperItem, StepperTitle, StepperDescription } from "@/components/ui/stepper"
<Stepper value={currentStep} orientation="horizontal">
<StepperItem>
<StepperTitle>اطلاعات</StepperTitle>
<StepperDescription>نام و شماره تماس</StepperDescription>
</StepperItem>
<StepperItem>
<StepperTitle>پرداخت</StepperTitle>
</StepperItem>
</Stepper>این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
ترکیب اجزا
Stepper فقط value (شاخصِ صفرپایهٔ مرحلهٔ فعال) می‌گیرد و خودش وضعیتِ complete/active/upcoming هر StepperItem را از روی جای آن در فهرست فرزندان حساب می‌کند؛ لازم نیست این وضعیت را دستی به هر مرحله بدهید. شمارهٔ مرحله، اولین/آخرین بودن و رنگِ خطِ رابط هم از همین ترتیب می‌آید.
این محاسبه با context انجام می‌شود، پس StepperItemی که داخلِ .map، یک Fragment یا کامپوننتِ پوشانندهٔ خودتان باشد هم درست کار می‌کند. propهای status، prevStatus، stepIndex، isFirst و isLast فقط برای override هستند (مثلاً مرحلهٔ ردشده‌ای که باید upcoming بماند)؛ اگر بدهید بر مقدارِ محاسبه‌شده برنده‌اند.
برای رفتن به مرحلهٔ بعد/قبل فقط value را از بیرون تغییر دهید (خودِ Stepper state ندارد، کنترل‌شده است).
دسترس‌پذیری
- ظرف role=list دارد و هر مرحله role=listitem؛ مرحلهٔ فعال aria-current=step می‌گیرد.
- Stepper خودش تعاملی/کلیک‌پذیر نیست (فقط نشان‌دهندهٔ وضعیت)؛ اگر می‌خواهید کاربر با کلیک به مرحلهٔ قبلی برگردد، خودِ StepperItem را با onClick/role=button بسازید.
- رنگ به‌تنهایی حامل معنا نیست؛ عدد/چک‌مارک و متن عنوان هم همیشه هستند.
مرجع API
Stepper
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value | number | — | شاخص (صفرپایه) مرحلهٔ فعال. |
| orientation | "horizontal" | "vertical" | "horizontal" | جهت چیدمان مراحل. |
| children | React.ReactNode | — | چند StepperItem. |
StepperItem
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| icon | React.ReactNode | ((status: StepStatus) => React.ReactNode) | — | آیکون سفارشی به‌جای شمارهٔ مرحله؛ تابع، آیکونِ هر وضعیت را جدا می‌دهد. |
| status | "complete" | "active" | "upcoming" | از value و جایگاه | فقط override؛ داخلِ Stepper خودکار حساب می‌شود. |
| stepIndex | number | ترتیبِ فرزند | فقط override؛ شاخصِ صفرپایهٔ مرحله (عددِ نشانگر = stepIndex + 1). |
| prevStatus / isFirst / isLast | StepStatus / boolean / boolean | از ترتیبِ فرزندان | فقط override؛ رنگ و نمایشِ نیمه‌های خطِ رابط را تعیین می‌کنند. |
| children | React.ReactNode | — | StepperTitle و/یا StepperDescription. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
نمونه‌ها
عمودی
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
از روی آرایه (map)
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
همهٔ مراحل انجام‌شده
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
مرحلهٔ اول (هیچ‌کدام انجام‌نشده)
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
سبک چک‌باکس
با override کردنِ icon هر StepperItem، به‌جای شماره یک نقطهٔ ساده برای مرحلهٔ فعال و دایرهٔ خالی برای مراحل باقی‌مانده نشان می‌دهیم. برای دایرهٔ خالی icon={<span />} بدهید، نه Fragment خالی یا null: آن‌ها «بدون آیکون» خوانده می‌شوند و شماره برمی‌گردد. در عرضِ باریک، مراحل حداقل عرض دارند و Stepper افقی اسکرول می‌خورد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
آیکون در جعبه + خط رنگی
به‌جای دایره، آیکون داخل جعبهٔ گرد می‌نشیند و خط رابط بالای هر ستون، رنگِ وضعیت را نشان می‌دهد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
فشرده با متنِ وضعیت
از children آزادِ StepperItem استفاده شده: زیرِ عنوان، یک خط متنِ وضعیت با رنگِ مخصوصِ خودش اضافه شده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
عمودی با خط توپُر و نشانگر نقطه‌ای
برخلافِ حالتِ پیش‌فرضِ عمودیِ Stepper (که برای مراحلِ باقی‌مانده خط‌چین نشان می‌دهد)، اینجا خط همیشه توپُر است و مرحلهٔ فعال به‌جای شماره، یک نشانگرِ نقطه‌ای در وسطِ حلقه دارد؛ برای همین با نشانگر و اتصال‌دهندهٔ سفارشی ساخته شده، نه پیش‌فرضِ StepperItem.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار می‌آید |
|---|---|
| عمودی | پیگیری سفارش یا کارت خلاصهٔ فرآیند، جایی که هر مرحله توضیح یا زمان کنارش لازم دارد |
| از روی آرایه (map) | ویزاردی که مراحلش از داده می‌آید؛ هیچ propِ وضعیت یا شاخصی دستی داده نمی‌شود |
| همهٔ مراحل انجام‌شده | صفحهٔ رسید/خلاصهٔ پایانِ فرآیند، برای تایید بصری که هیچ مرحله‌ای جا نمانده |
| مرحلهٔ اول (هیچ‌کدام انجام‌نشده) | شروع یک فرم یا ویزارد چندمرحله‌ای، پیش از هر ورودی از کاربر |
| سبک چک‌باکس | فرم‌های طولانی با تعداد مراحل زیاد (۵ تا ۶ تا)، جایی که شماره‌گذاری اهمیتی ندارد |
| آیکون در جعبه + خط رنگی | داشبورد یا صفحهٔ راه‌اندازی حساب که هر مرحله یک بخش کاملاً متفاوت از تنظیمات است |
| فشرده با متنِ وضعیت | پنل مدیریتی یا سفارش‌ها که باید وضعیتِ متنیِ هر مرحله (تکمیل‌شده/در حال انجام/در انتظار) هم دیده شود |
| عمودی با خط توپُر و نشانگر نقطه‌ای | چک‌لیستِ تسویه‌حساب یا فرآیندی که همهٔ مراحل (حتی باقی‌مانده) باید با یک خطِ پیوسته به هم وصل به‌نظر برسند |