Progressv1.0.0
نواری که میزان پیشرفت یک عملیات را نشان می‌دهد؛ در چیدمان راست‌به‌چپ از سمت راست پر می‌شود. برای فضاهای فشرده‌تر (آواتار، کارت‌های کوچک) از ProgressCircle استفاده کنید.
این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نصب
با CLI اختصاصی digdesign کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.
npx digdesign@latest add https://docs.digdesign.ir/r/progress.jsonpnpm dlx digdesign@latest add https://docs.digdesign.ir/r/progress.jsonyarn dlx digdesign@latest add https://docs.digdesign.ir/r/progress.jsonbunx --bun digdesign@latest add https://docs.digdesign.ir/r/progress.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
استفاده
import { Progress } from "@/components/ui/progress"
<Progress value={33} />این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
ترکیب اجزا
Progress خودش را با value/min/max اندازه می‌گیرد؛ برای نمایش عدد کنار نوار (که عمداً داخل کامپوننت نیست، مثل Slider) از formatNumber در lib/persian کنار یک Label استفاده کنید.
ProgressCircle همان propهای value/min/max/size/color/indeterminate/formatOptions را دارد، فقط به‌جای نوار، یک کمان SVG می‌کشد.
دسترس‌پذیری
- نقش progressbar و aria-valuemin/aria-valuemax/aria-valuenow به‌صورت خودکار تنظیم می‌شوند؛ با formatOptions، aria-valuetext هم مقدار را با ارقام فارسی برای صفحه‌خوان می‌خواند (مثلاً «۶۶٪» به‌جای عدد خام).
- برای پیشرفت نامشخص (وقتی مدت واقعی عملیات معلوم نیست)، value ندهید و indeterminate بدهید؛ در این حالت aria-valuenow حذف می‌شود تا صفحه‌خوان اعلام کند مقدار دقیق در دسترس نیست، نه اینکه آن را صفر بخواند.
- اگر برچسب دیداری کنار نوار نمی‌گذارید، aria-label بدهید.
مرجع API
Progress
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value | number | — | مقدار فعلی بین min و max. |
| min | number | 0 | حداقل مقدار. |
| max | number | 100 | حداکثر مقدار. |
| indeterminate | boolean | false | پیشرفت نامشخص؛ value نادیده گرفته می‌شود و aria-valuenow حذف می‌شود. |
| size | "sm" | "md" | "lg" | "md" | ارتفاع نوار. |
| color | "default" | "primary" | "success" | "warning" | "destructive" | "primary" | رنگ بخش پرشده. |
| formatOptions | Intl.NumberFormatOptions | { style: "percent" } | قالب مقدار در aria-valuetext (با formatNumber و ارقام فارسی)؛ روی نمایش دیداری اثر ندارد. |
ProgressCircle
همان propهای بالا را دارد، به‌علاوهٔ strokeWidth برای ضخامت کمان (پیش‌فرض متناسب با size).
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| strokeWidth | number | — | ضخامت کمان به px؛ پیش‌فرض بر اساس size تعیین می‌شود. |
data-slot
هر جزء داخلی یک data-slot دارد؛ برای استایل‌دهی سفارشی از همین‌ها استفاده کنید.
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| progress-indicator | div | — | بخش پرشدهٔ نوار خطی. |
| progress-circle-track | circle | — | کمان پس‌زمینهٔ حلقهٔ دایره‌ای. |
| progress-circle-fill | circle | — | کمان پرشدهٔ حلقهٔ دایره‌ای. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
نمونه‌ها
Values
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
اندازه‌ها
size سه مقدار دارد: sm، md (پیش‌فرض) و lg.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
رنگ‌ها
color نوار پرشده را رنگ می‌کند؛ نوار پس‌زمینه همیشه خاکستری خنثی می‌ماند تا رنگ‌ها روی آن خوانا بمانند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نامشخص (indeterminate)
وقتی مدت واقعی عملیات معلوم نیست؛ نوار به‌جای نمایش درصد، به‌آرامی تپش می‌گیرد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
همراه با برچسب مقدار
formatOptions فقط aria-valuetext را قالب‌بندی می‌کند؛ برای برچسب دیداری، مثل Slider، عدد را خودتان با formatNumber کنار برچسب چاپ کنید.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
بازهٔ سفارشی
min/max بازهٔ دلخواه (نه فقط ۰ تا ۱۰۰) می‌سازد؛ برای مقادیری مثل امتیاز یا تعداد قدم مناسب است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
حلقهٔ دایره‌ای (ProgressCircle)
همان API خطی را دارد؛ برای فضاهای فشرده مثل روی آواتار یا داخل کارت‌های کوچک مناسب‌تر است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
معلوم در برابر نامعلوم
اگر درصد را می‌دانید، عدد را کنار نوار بنویسید؛ نوار به‌تنهایی دقتش کم است. اگر نمی‌دانید، صفر درصد نشان ندهید چون شبیه گیرکردن است؛ نوار نامعلوم بگذارید.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
خوانا برای صفحه‌خوان
نوار بدون برچسب برای صفحه‌خوان فقط یک عدد بی‌نام است. aria-label بگویید مالِ چیست و با aria-valuetext مقدار را با ارقام فارسی بدهید.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار می‌آید |
|---|---|
| Values | فهرست چند وظیفهٔ هم‌زمان که هرکدام درصد پیشرفت جداگانه دارند |
| اندازه‌ها | size سه مقدار دارد: sm، md (پیش‌فرض) و lg. |
| رنگ‌ها | color نوار پرشده را رنگ می‌کند؛ نوار پس‌زمینه همیشه خاکستری خنثی می‌ماند تا رنگ‌ها روی آن خوانا بمانند. |
| نامشخص (indeterminate) | وقتی مدت واقعی عملیات معلوم نیست؛ نوار به‌جای نمایش درصد، به‌آرامی تپش می‌گیرد. |
| همراه با برچسب مقدار | formatOptions فقط aria-valuetext را قالب‌بندی می‌کند؛ برای برچسب دیداری، مثل Slider، عدد را خودتان با formatNumber کنار برچسب چاپ کنید. |
| بازهٔ سفارشی | min/max بازهٔ دلخواه (نه فقط ۰ تا ۱۰۰) می‌سازد؛ برای مقادیری مثل امتیاز یا تعداد قدم مناسب است. |
| حلقهٔ دایره‌ای (ProgressCircle) | همان API خطی را دارد؛ برای فضاهای فشرده مثل روی آواتار یا داخل کارت‌های کوچک مناسب‌تر است. |
| معلوم در برابر نامعلوم | آپلود با درصد مشخص، در برابر همگام‌سازی با زمان نامعلوم |
| خوانا برای صفحه‌خوان | هر نوار پیشرفتی که وضعیتش مهم است |
دستورالعمل استفاده
فقط برای پیشرفت قابل‌اندازه‌گیری
انجام بده
وقتی درصد واقعی پیشرفت را می‌دانید (مثل آپلود فایل یا تکمیل فرم چندمرحله‌ای)، همان عدد را در value بگذارید.
انجام نده
برای عملیاتی که مدت‌زمانش نامشخص است، عدد ثابت و دلبخواهی مثل ۵۰ نگذارید؛ کاربر فکر می‌کند عملیات نیمه‌کاره متوقف شده. به‌جایش indeterminate بدهید.
به‌روزرسانی پیوسته، نه پرش ناگهانی
در حال آپلود… ۳۵٪
انجام بده
مقدار را هر چند ثانیه یک‌بار متناسب با پیشرفت واقعی افزایش دهید تا نوار حسی از حرکت واقعی بدهد.
در حال آپلود…
انجام نده
مقدار را از ۰ مستقیم به ۱۰۰ نپرانید؛ این کار حس واقعی‌بودن پیشرفت را از بین می‌برد و اگر عملیات هنوز تمام نشده، کاربر را گیج می‌کند.