پرتوپرتو

داده‌نمایی

راهنمای استفاده از نمودارها و ویژوالیزیشن داده در پرتو — رنگ، دسترسی‌پذیری، و الگوها

پلتفرم‌های سوشال لیسنینگ داده-محور هستند. این صفحه اصول و الگوهای استفاده از نمودارها در پرتو را توضیح می‌دهد.


نمودارهای موجود

همهٔ خروجی‌های نمودار پیشوند Parto دارند. نسخهٔ پیشین این جدول نام‌هایی مثل BarChart و PieChart را فهرست می‌کرد که هیچ‌گاه export نشده‌اند — قطعه‌کدهای پایین همین صفحه از نام درست استفاده می‌کردند، پس جدول و کد یکدیگر را نقض می‌کردند.

کامپوننتکاربرد
PartoLineChartروند زمانی (منشن، نرخ تعامل در طول زمان)
PartoAreaChartروند زمانی با تأکید بر حجم انباشته
PartoBarChartمقایسه (پلتفرم‌ها، دسته‌ها)
PartoPieChartتوزیع (احساسات، سهم پلتفرم)
PartoRadarChartمقایسهٔ چندمعیاره (پروفایل در برابر پروفایل)
PartoScatterChartهمبستگی دو معیار
PartoHeatMapتراکم زمانی (بهترین ساعات پست)
PartoWordCloudفراوانی کلمات (هشتگ‌ها، موضوعات)
PartoSankeyChartجریان بین دسته‌ها
PartoNetworkChartشبکهٔ ارتباط بین حساب‌ها
ConceptPulseChartضربان یک مفهوم در زمان

Sparkline برای نمودار درون‌خطی داخل کارت، ChartCard برای قالب کارت نمودار، و EmptyChart برای حالت بی‌داده است — این سه نوع نمودار نیستند، پوشش و حالت‌اند.


رنگ‌های نمودار

هشت رنگ پایه

پرتو هشت توکن رنگی اختصاصی برای نمودارها دارد که در هر دو تم (روشن و تاریک) کار می‌کنند:

--chart-1  /* رنگ اول — اصلی */
--chart-2  /* رنگ دوم */
--chart-3  /* رنگ سوم */
--chart-4  /* رنگ چهارم */
--chart-5  /* رنگ پنجم */
--chart-6  /* رنگ ششم */
--chart-7  /* رنگ هفتم */
--chart-8  /* رنگ هشتم */

ساده‌ترین راه، استفاده از hook آماده useChartTheme() است که آرایه‌ی chartColors (هر هشت رنگ) را در زمان رندر و هماهنگ با تم برمی‌گرداند:

import { useChartTheme } from '@partodata/ui'

// داخل نمودارها به صورت خودکار اعمال می‌شود
const { chartColors } = useChartTheme()
// chartColors → آرایه‌ای از هشت رنگ آماده‌ی استفاده

اگر بخواهید یک توکن را دستی بخوانید، از useRootStyles() استفاده کنید. این hook یک CSSStyleDeclaration (یا null پیش از mount) برمی‌گرداند؛ متغیرهای CSS باید با getPropertyValue خوانده شوند، نه با ایندکس براکتی:

import { useRootStyles } from '@partodata/ui'

const styles = useRootStyles()
const chartColors = [
  styles?.getPropertyValue('--chart-1').trim(),
  styles?.getPropertyValue('--chart-2').trim(),
  styles?.getPropertyValue('--chart-3').trim(),
]

رنگ‌های احساسات در نمودار

برای نمودارهای sentiment، از توکن‌های اختصاصی استفاده کنید:

const sentimentColors = {
  positive: styles?.getPropertyValue('--sentiment-positive').trim(),
  neutral: styles?.getPropertyValue('--sentiment-neutral').trim(),
  negative: styles?.getPropertyValue('--sentiment-negative').trim(),
}

رنگ‌های تعامل در نمودار

const engagementColors = {
  excellent: styles?.getPropertyValue('--engagement-excellent').trim(),
  'very-good': styles?.getPropertyValue('--engagement-very-good').trim(),
  good: styles?.getPropertyValue('--engagement-good').trim(),
  average: styles?.getPropertyValue('--engagement-average').trim(),
  low: styles?.getPropertyValue('--engagement-low').trim(),
  poor: styles?.getPropertyValue('--engagement-poor').trim(),
}

تغییر تم

برای مشاهده نمودارها در تم‌های مختلف:

رنگ‌های نمودار به صورت خودکار با تغییر تم به‌روز می‌شوند — نیازی به هیچ تنظیم اضافه‌ای نیست.


الگوهای کاربردی

نمودار خط — روند منشن‌ها

import { PartoLineChart } from '@partodata/ui'
;<PartoLineChart data={mentionData} dataKeys={['count']} xAxisKey="date" isLoading={isLoading} />

نمودار دایره — توزیع احساسات

import { PartoPieChart } from '@partodata/ui'
;<PartoPieChart
  data={[
    { name: 'مثبت', value: 65 },
    { name: 'خنثی', value: 25 },
    { name: 'منفی', value: 10 },
  ]}
  isLoading={isLoading}
/>

نمودار میله‌ای — مقایسه پلتفرم

import { PartoBarChart } from '@partodata/ui'
;<PartoBarChart data={platformData} keys={['mentions', 'engagement']} indexBy="platform" isLoading={isLoading} />

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

همه نمودارها از prop isLoading پشتیبانی می‌کنند. در حالت loading، نمودار با Skeleton جایگزین می‌شود:

<PartoLineChart
  data={data}
  dataKeys={['count']}
  xAxisKey="date"
  isLoading={isLoading} // ← Skeleton نمایش می‌دهد
/>

دسترسی‌پذیری نمودارها

نمودارها به تنهایی برای screen readerها قابل درک نیستند. همیشه یک خلاصه متنی ارائه دهید:

<div>
  <PartoLineChart data={data} dataKeys={['count']} xAxisKey="date" isLoading={isLoading} />

  {/* خلاصه برای screen readers */}
  <p className="sr-only">نمودار روند منشن‌ها در ۳۰ روز گذشته. بیشترین منشن در تاریخ ۱۵ اسفند با ۲۳۴ مورد بوده است.</p>
</div>

بهترین روش‌ها

انتخاب نمودار مناسب

سوالنمودار پیشنهادی
روند در طول زمان چیست؟LineChart
چند دسته را با هم مقایسه کنم؟BarChart
سهم هر بخش چقدر است؟PieChart
پیک‌های زمانی کجاست؟HeatMap
پرتکرارترین کلمات کدام‌اند؟WordCloud

محدودیت‌ها

  • برای PieChart بیش از ۵ بخش استفاده نکنید — خوانایی کاهش می‌یابد
  • برای LineChart بیش از ۴ خط هم‌زمان نمایش ندهید
  • همیشه isLoading را هندل کنید
  • همیشه sr-only خلاصه متنی اضافه کنید