پیشرفت دایره‌ای (CircularProgress)

معرفی

کامپوننت CircularProgress برای نمایش مقدار درصدی به شکل یک حلقه دایره‌ای استفاده می‌شود. مناسب برای نمایش نرخ تعامل، درصد تکمیل، یا هر معیار 0 تا 100 است.

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

• برای نمایش درصد تکمیل در فضای مربعی یا دایره‌ای
• وقتی نمایش بصری حلقه‌ای مناسب‌تر از نوار خطی است
• برای نمایش یک مقدار درصدی برجسته (مثلاً نرخ تعامل، امتیاز)

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

• برای مقادیر linear با مقایسه — از Progress استفاده کنید
• برای نمایش loading — از Spinner استفاده کنید

زمین بازی

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

import { CircularProgress } from '@partodata/ui'

<CircularProgress />

استفاده

import { CircularProgress } from '@partodata/ui'

export default function MyComponent() {
  return <CircularProgress value={72} variant="success" label="نرخ تعامل" />
}

انواع

رنگ‌بندی‌ها

از prop variant برای تنظیم رنگ حلقه پیشرفت استفاده کنید. شش حالت پشتیبانی می‌شود: primary، success، warning، destructive و دو حالت جدید info (آبی) و neutral (خاکستری).

اندازه‌ها

با تنظیم diameter می‌توانید اندازه دلخواه را انتخاب کنید.

قالب‌بندی درصد

پراپ locale هم رقم و هم نشانهٔ درصد را کنترل می‌کند. مقدار پیش‌فرض fa است و خروجی فارسی و عربی با نشانهٔ ٪ نمایش داده می‌شود؛ برای رابط انگلیسی locale="en" را تنظیم کنید تا نشانهٔ % نمایش داده شود. نشانه را در consumer به مقدار عددی نچسبانید.

Props

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

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

• از role="progressbar" و aria-valuenow، aria-valuemin، aria-valuemax پشتیبانی می‌کند
• label علاوه بر نمایش داخل دایره، با aria-labelledby نام دسترسی‌پذیر progressbar را می‌سازد؛ بنابراین صفحه‌خوان «نرخ تعامل، 72» را اعلام می‌کند، نه فقط عدد را
• اگر label ندهید، نام دسترسی‌پذیر به‌صورت پیش‌فرض «درصد پیشرفت» (متناسب با locale) است؛ برای نام دقیق‌تر می‌توانید aria-label یا aria-labelledby را مستقیم بدهید که بر هر دو اولویت دارد
• در حالت RTL، جهت انیمیشن به درستی تنظیم می‌شود

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

• Progress — اگر نمایش خطی مناسب‌تر است (مثلاً در فضای افقی)، از Progress استفاده کنید
• Spinner — اگر درصد مشخصی ندارید و فقط حالت بارگذاری می‌خواهید، از Spinner استفاده کنید