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

معرفی

کامپوننت PartoBarChart برای نمایش و مقایسه مقادیر عددی به صورت نمودار میله‌ای طراحی شده است. این کامپوننت بر پایه Recharts ساخته شده و به‌طور خودکار رنگ‌های تم سیستم طراحی را اعمال می‌کند. از حالت‌های گروهی و تجمعی، چیدمان عمودی و افقی، و بارگذاری Skeleton پشتیبانی می‌کند.

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

• برای مقایسه مقادیر عددی بین دسته‌های مختلف (مثلاً عملکرد پلتفرم‌ها)
• برای نمایش رتبه‌بندی یا توزیع مقادیر categorical
• برای مقایسه چند سری داده در کنار یکدیگر (حالت grouped)

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

• برای داده‌های time-series با نقاط زیاد — از LineChart استفاده کنید
• برای نمایش سهم‌ها — از PieChart استفاده کنید
• برای توزیع matrix — از HeatMap استفاده کنید

راهنمای groupMode:

• grouped — مقایسه مستقیم مقادیر بین سری‌ها در هر دسته
• stacked — نمایش مجموع کل با توزیع داخلی
• horizontal — وقتی label های محور X طولانی هستند یا فضای عمودی محدود است

استفاده پایه

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

const data = [
  { ماه: 'فروردین', فروش: 50, هزینه: 32 },
  { ماه: 'اردیبهشت', فروش: 80, هزینه: 45 },
  { ماه: 'خرداد', فروش: 65, هزینه: 40 },
  { ماه: 'تیر', فروش: 95, هزینه: 58 },
]

<div className="h-[400px]">
  <PartoBarChart
    data={data}
    keys={['فروش', 'هزینه']}
    indexBy="ماه"
    margin={{ top: 20, right: 20, bottom: 50, left: 60 }}
  />
</div>

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

حالت گروهی

در حالت گروهی، میله‌های مربوط به هر سری داده در کنار یکدیگر قرار می‌گیرند. این حالت برای مقایسه مستقیم مقادیر مناسب است.

<PartoBarChart data={data} keys={['فروش', 'هزینه']} indexBy="ماه" groupMode="grouped" />

حالت تجمعی (Stacked)

در حالت تجمعی، میله‌ها روی هم قرار می‌گیرند و مجموع کل قابل مشاهده است.

<PartoBarChart data={data} keys={['فروش', 'هزینه']} indexBy="ماه" groupMode="stacked" />

چیدمان افقی

برای نمایش در فضای عمودی محدود یا برچسب‌های طولانی، از چیدمان افقی استفاده کنید.

<PartoBarChart
  data={data}
  keys={['فروش']}
  indexBy="ماه"
  layout="horizontal"
  margin={{ top: 20, right: 20, bottom: 50, left: 80 }}
/>

با برچسب مقادیر

<PartoBarChart data={data} keys={['فروش']} indexBy="ماه" enableLabel={true} />

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

<PartoBarChart
  data={data}
  keys={['فروش', 'هزینه']}
  indexBy="ماه"
  tooltipFormatter={(name, value) => (
    <span>
      {name}: <strong>{value.toLocaleString('fa-IR')}</strong> واحد
    </span>
  )}
/>

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

<PartoBarChart data={[]} keys={['فروش']} indexBy="ماه" isLoading={true} />

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

ویژگی‌های اصلی

ویژگی‌های ظاهری

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

حالت نمایش (groupMode)

چیدمان (layout)

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

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

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

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

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

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

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

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

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

• LineChart — اگر داده‌های شما time-series هستند و نیاز به نمایش روند دارید، LineChart مناسب‌تر است
• PieChart — اگر می‌خواهید سهم نسبی هر بخش از کل را نمایش دهید، PieChart را انتخاب کنید
• HeatMap — اگر داده‌های شما ماتریسی (دو بُعدی) هستند، از HeatMap استفاده کنید
• داده‌نمایی — راهنمای کامل رنگ‌بندی و تم نمودارها