نمودار دایره‌ای (Pie Chart)

معرفی

کامپوننت PartoPieChart برای نمایش نسبت‌ها و درصدها به صورت نمودار دایره‌ای یا حلقه‌ای (Donut) طراحی شده است. این کامپوننت بر پایه Recharts ساخته شده و به‌طور پیش‌فرض به صورت حلقه‌ای نمایش داده می‌شود. رنگ‌ها به‌طور خودکار از تم سیستم طراحی خوانده می‌شوند.

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

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

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

• برای بیش از ۶ بخش — خوانایی کاهش می‌یابد، از BarChart استفاده کنید
• برای مقایسه مقادیر دقیق — از BarChart استفاده کنید
• برای داده‌های time-series — از LineChart استفاده کنید

استفاده پایه

import { PartoPieChart } from '@parto-system-design/ui'

const data = [
  { name: 'محصول A', value: 40 },
  { name: 'محصول B', value: 25 },
  { name: 'محصول C', value: 20 },
  { name: 'محصول D', value: 15 },
]

<div className="h-[400px]">
  <PartoPieChart
    data={data}
    innerRadius="60%"
    paddingAngle={1.2}
    cornerRadius={4}
    showLabels
  />
</div>

نمونه‌های کاربردی

نمودار دایره‌ای کامل (Pie)

برای نمایش نمودار دایره‌ای بدون حفره مرکزی، مقدار innerRadius را برابر 0 قرار دهید.

<PartoPieChart data={data} innerRadius={0} paddingAngle={0.7} cornerRadius={3} showLabels />

نمودار حلقه‌ای (Donut)

حالت پیش‌فرض کامپوننت، حلقه‌ای با innerRadius="60%" است.

<PartoPieChart data={data} innerRadius="60%" paddingAngle={1.2} cornerRadius={4} />

بدون برچسب‌های اتصال

<PartoPieChart data={data} showLabels={false} />

رد کردن برچسب قطعات کوچک

با ویژگی labelSkipAngle می‌توانید برچسب قطعاتی که زاویه کمتری دارند را مخفی کنید.

<PartoPieChart data={data} showLabels labelSkipAngle={20} />

سفارشی‌سازی Tooltip

<PartoPieChart
  data={data}
  tooltipFormatter={(name, value) => (
    <span>
      {name}: <strong>{value.toLocaleString('fa-IR')}</strong> واحد
    </span>
  )}
/>

حالت بارگذاری

<PartoPieChart data={[]} isLoading={true} />

جدول ویژگی‌ها

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

نوع نمودار

حالت بارگذاری (isLoading)

با isLoading={true} یک Skeleton متحرک به‌جای نمودار نمایش داده می‌شود.

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

تم‌بندی خودکار

این کامپوننت به‌طور خودکار از متغیرهای CSS سیستم طراحی استفاده می‌کند:

• رنگ‌های قطعات از --chart-1 تا --chart-5 خوانده می‌شوند
• با هر دو تم (روشن و تاریک) سازگار است
• Tooltip با رنگ پس‌زمینه و حاشیه مناسب تم نمایش داده می‌شود
• برچسب‌ها با رنگ foreground هماهنگ هستند

مقایسه با نمودار میله‌ای

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

• کامپوننت دارای role="img" و پشتیبانی از ariaLabel برای صفحه‌خوان‌ها است
• در حالت بارگذاری از role="status" استفاده می‌شود
• رنگ‌های قطعات کنتراست کافی با یکدیگر و پس‌زمینه دارند
• Tooltip با تعامل ماوس و لمسی فعال می‌شود

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

• SentimentDistribution — اگر داده شما توزیع احساسات (مثبت/منفی/خنثی) است، از این کامپوننت اختصاصی استفاده کنید
• BarChart — اگر نیاز به مقایسه دقیق مقادیر عددی دارید، BarChart دقت بصری بیشتری ارائه می‌دهد
• LineChart — اگر داده‌های شما time-series هستند و نمایش روند مهم است
• داده‌نمایی — راهنمای کامل نمودارها و اصول رنگ‌بندی