مراحل — Stepper

مراحل فهرست مرتب یک فرایند چندمرحله‌ای است، مثل ثبت ایده یا راه‌اندازی محصول. کامپوننت وضعیت هر مرحله (تکمیل‌شده، فعلی، در انتظار) را همزمان با آیکون یا عدد و با متن برای صفحه‌خوان نشان می‌دهد؛ بنابراین رنگ تنها نشانهٔ وضعیت نیست. با دادن مرحله‌های تکمیل‌شده دکمه می‌شوند تا کاربر بتواند به عقب برگردد. ساختار و و منطق وضعیت مراحل ثابت است.

وضعیت: beta · لایه: ۳ () · کد:

TSX

import { Stepper } from '@tokapps/tuk';

نمونهٔ زنده

کد قابل کپی

TSX

import { Stepper } from '@tokapps/tuk';const steps = [  { id: 'info', label: 'اطلاعات پایه', description: 'عنوان و دسته‌بندی' },  { id: 'detail', label: 'شرح ایده', description: 'مسئله و راه‌حل' },  { id: 'team', label: 'تیم', optional: true },  { id: 'review', label: 'بازبینی و ارسال' },];export function HorizontalStepper() {  return <Stepper steps={steps} current={1} aria-label="مراحل ثبت ایده" />;}

TSX

import { useState } from 'react';import { Stepper } from '@tokapps/tuk';const steps = [  { id: 'info', label: 'اطلاعات پایه', description: 'عنوان و دسته‌بندی' },  { id: 'detail', label: 'شرح ایده', description: 'مسئله و راه‌حل' },  { id: 'team', label: 'تیم', optional: true },  { id: 'review', label: 'بازبینی و ارسال' },];// مرحلهٔ تکمیل‌شده دکمه می‌شود و کاربر به عقب برمی‌گرددexport function NavigableVerticalStepper() {  const [current, setCurrent] = useState(2);  return (    <Stepper      steps={steps}      current={current}      orientation="vertical"      onStepClick={(index) => setCurrent(index)}      aria-label="مراحل ثبت ایده"    />  );}

TSX

import { Stepper } from '@tokapps/tuk';const steps = [  { id: 'info', label: 'اطلاعات پایه' },  { id: 'review', label: 'بازبینی و ارسال' },];// حالت شروع: هیچ مرحله‌ای تکمیل نشده و مرحلهٔ فعلی اول است؛ ارقام لاتینexport function StartStateStepper() {  return <Stepper steps={steps} current={0} digits="latin" aria-label="مراحل ثبت ایده" print="show" />;}

همهٔ پیکربندی‌ها

پراپ	نوع	پیش‌فرض	توضیح
		— (الزامی)	فهرست مراحل؛ هر مرحله ، ، و دارد.
		— (الزامی)	اندیس مرحلهٔ فعلی، ۰-مبنا. مقدار خارج از بازه محدود (clamp) نمی‌شود.
			جهت چیدمان. در موبایل افقی به عمودی تبدیل می‌شود.
		—	فقط برای مرحله‌های تکمیل‌شده فعال می‌شود و آن‌ها را دکمه می‌کند.
			ارقام نشانگر مرحله‌ها.
		متن فارسی پیش‌فرض (، ، ، ، تابع )	برچسب‌های وضعیت برای صفحه‌خوان و متن «اختیاری». پاس دادن این پراپ کل مقدار پیش‌فرض را جایگزین می‌کند؛ هر پنج کلید را باید بدهید.
			برچسب برای صفحه‌خوان.
			پیش‌فرض در چاپ دیده می‌شود.
		—	کلاس اضافی روی .

پراپ‌های :

فیلد	نوع	پیش‌فرض	توضیح
		— (الزامی)	کلید یکتای مرحله.
		— (الزامی)	عنوان مرحله.
		—	توضیح کوتاه زیر عنوان.
		—	اگر باشد، متن «اختیاری» کنار مرحله می‌آید.

ساختار و اسلات‌ها

با
- - (برای هر مرحله)
    - (فقط مرحلهٔ تکمیل‌شده با ) یا
      - با ✓ یا عدد
      - (اختیاری)
        
        (اگر )
        
        (متن وضعیت برای صفحه‌خوان؛ در چاپ نمایش داده می‌شود)

بنیان ثابت: ساختار ، روی مرحلهٔ فعلی، و اتصال‌دهنده بین مرحله‌ها.

بخش قابل‌تغییر: ، ، ، ، و .

همهٔ حالت‌ها

حالت	نشانه	نمایش
complete	روی	نشانگر پر با و آیکون ✓؛ برچسب با رنگ ؛ اتصال‌دهنده با .
current	و	حلقهٔ اکسنت با پس‌زمینهٔ ؛ برچسب پررنگ.
upcoming		نشانگر خطی با ؛ برچسب با .
hover	روی دکمهٔ مرحلهٔ تکمیل‌شده	پس‌زمینهٔ .
focus-visible	روی دکمه	حلقهٔ فوکوس . فقط مرحله‌های تکمیل‌شدهٔ قابل‌کلیک فوکوس‌پذیرند.
optional		متن «اختیاری» با رنگ .
عمودی		مراحل زیر هم و اتصال‌دهنده عمودی.
موبایل	رسانه	حالت افقی ستونی می‌شود و اتصال‌دهنده پنهان است.
چاپ	یا	پیش‌فرض دیده می‌شود؛ در چاپ به متن عادی تبدیل می‌شود.

کامپوننت حالت‌های disabled، invalid، loading و readonly ندارد؛ در کد تعریف نشده‌اند.

تغییرات مجاز برای توسعه‌دهنده

variant: و از طریق .
size: یک اندازه ()؛ اندازهٔ جداگانه‌ای در کد تعریف نشده است.
وضعیت‌ها: با مرحلهٔ فعلی تعیین می‌شود؛ مرحله‌های بالاتر در انتظار و پایین‌تر تکمیل‌شده‌اند.
بازگشت: برای برگشت به مرحلهٔ تکمیل‌شده.
برچسب‌ها و ارقام: برای ترجمهٔ کامل متن وضعیت و برای ارقام نشانگر.
نقاط توسعه: ، ، توکن‌های ، ، .
صدا و handler: رویداد صوتی ندارد؛ فقط رویداد کلیک را اعلام می‌کند.

تغییرات ممنوع (بنیان ثابت)

حذف از مرحلهٔ فعلی یا جایگزینی آن با .
حذف متن وضعیت () یا تکیه بر رنگ تنها برای نمایش وضعیت.
قابل‌کلیک‌کردن مرحله‌های در انتظار یا فعلی.
تغییر ترتیب یا حذف .
هدف لمسی کمتر از ۴۴ پیکسل برای دکمهٔ مرحلهٔ تکمیل‌شده.
حذف فوکوس مرئی یا انیمیشن در .

RTL، کیبورد و صفحه‌خوان

RTL: ترتیب مرحله‌ها از راست به چپ است و اتصال‌دهنده با ویژگی‌های منطقی () رسم می‌شود. اعداد پیش‌فرض فارسی‌اند.
کیبورد: فقط روی مرحله‌های تکمیل‌شدهٔ قابل‌کلیک می‌ایستد؛ یا به آن مرحله برمی‌گرداند. بقیهٔ مراحل ایستا هستند.
صفحه‌خوان: با (پیش‌فرض «مراحل») و ؛ هر مرحله با متن «مرحلهٔ ۲ از ۴، مرحلهٔ فعلی» یا «تکمیل‌شده» یا «در انتظار» اعلام می‌شود.
هدف لمسی: دکمهٔ مرحلهٔ تکمیل‌شده حداقل ۴۴ پیکسل ارتفاع دارد.

صدا، حرکت، چاپ و کاهش حرکت

صدا: بی‌صدا (). پیشرفت مرحله‌ای صوتی ندارد و prop مربوط به در کد تعریف نشده است.
حرکت: نام معنایی با تغییر و (). با یا تغییر فوری است.
چاپ: پیش‌فرض نمایش (، رنگ تک‌رنگ). متن وضعیت هر مرحله در چاپ دیده می‌شود تا رنگ تنها نشانه نباشد ().

توکن‌ها

فایل توکن: و مقدارهای مرجع در .
توکن‌های معنایی مصرفی: ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، .
توکن‌های سطح کامپوننت (): ، ، ، ، ، ، ، ، ، ، ، ، ، .

قرارداد ARCH

آیکون ✓ فقط با و نام معنایی رندر می‌شود؛ مسیر asset در کد مصرف‌کننده نمی‌آید.
تم فقط حرکت و توکن را تغییر می‌دهد؛ ساختار DOM، ARIA و منطق وضعیت ثابت است.
gesture ندارد؛ بازگشت به مرحلهٔ قبل با کیبورد ( و ) و pointer یکسان است.

نکات

برای بخش‌های هم‌سطح غیرترتیبی از Tabs استفاده کنید.
برای نمایش درصد پیشرفت یک عملیات مشخص از Progress استفاده کنید.
برای جابه‌جایی بین صفحه‌های یک فهرست از Pagination استفاده کنید.
بیش از حدود ۷ مرحله معمولاً خوانا نیست؛ فرایند طولانی را به بخش‌ها تقسیم کنید.