نمایش آمار (StatDisplay)

معرفی

کامپوننت StatDisplay برای نمایش یک مقدار آماری به همراه برچسب، واحد و نشانگر روند استفاده می‌شود.

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

• برای نمایش یک عدد آماری ساده با برچسب توضیحی
• وقتی نمایش inline یک مقدار در کنار سایر محتوا لازم است
• برای نمایش مقادیر آماری بدون نیاز به sparkline یا differential

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

• برای متریک‌هایی که sparkline و differential دارند — از MetricCard استفاده کنید
• برای متن‌های توصیفی — StatDisplay مخصوص اعداد است

زمین بازی

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

استفاده

import { StatDisplay, TrendIndicator } from '@partodata/ui'
import { Users } from 'lucide-react'
;<StatDisplay value={1250000} label="دنبال‌کننده‌ها" icon={<Users />} trend={<TrendIndicator value={3.5} />} />

اندازه‌ها

<StatDisplay value={4500} label="بازدید" size="xs" />
<StatDisplay value={4500} label="بازدید" size="sm" /> {/* پیش‌فرض */}
<StatDisplay value={4500} label="بازدید" size="md" />
<StatDisplay value={4500} label="بازدید" size="lg" />
<StatDisplay value={4500} label="بازدید" size="xl" />

با واحد

<StatDisplay value={85} label="امتیاز" unit="٪" />
<StatDisplay value={1200} label="کاربران" unit="نفر" />

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

<StatDisplay value={0} label="در حال بارگذاری" isLoading />

نمایش آرام: emphasis="quiet"

برای آمار محیطی (ردیف فعالیت، خلاصهٔ درون‌خطی، ستون کناری) emphasis="quiet": مقدار در اندازهٔ متن بدنه، و آیکون در جعبهٔ 64 پیکسلی کنارش. href یا onClick کل آمار را پیوند یا دکمهٔ قابل‌دسترس با صفحه‌کلید می‌کند.

<StatDisplay emphasis="quiet" icon={<Users />} label="اعضای تیم" value="12 نفر" href="/team" />

Props

وزن مقدار

مقدار StatDisplay با وزن 400 رندر می‌شود، نه پررنگ. اندازهٔ پیش‌فرض sm نقش عدد شاخص است: .text-stat (24 / 32) با برچسب 13 / 500. اندازه‌های دیگر پله‌های صریح‌اند: xs = text-xl، md = text-3xl، lg = text-4xl، xl = text-5xl — فقط برای عددی که عمداً از ردیف KPI بزرگ‌تر است. برای یک آمار محیطی با عدد به اندازهٔ متن، emphasis="quiet".

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

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

• ریشهٔ کامپوننت role="group" می‌گیرد و نامش با aria-labelledby از همان label می‌آید، پس صفحه‌خوان عدد را همراه معنایش می‌خواند نه به‌صورت یک عدد شناور
• کل بلوک جهت صفحه را می‌گیرد؛ فقط خودِ عدد dir="ltr" دارد (یعنی unicode-bidi: isolate) تا علامت منفی جلوی رقم‌ها بماند. واحدهای فارسی مثل «نفر» بیرون از این ناحیه‌اند و در RTL کنار عدد می‌نشینند
• اعداد به locale مناسب فرمت می‌شوند (فارسی، عربی، انگلیسی)
• حالت بارگذاری از Skeleton استفاده می‌کند تا layout shift نداشته باشد

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

• MetricCard — اگر نیاز به sparkline و differential دارید، از MetricCard استفاده کنید
• TrendIndicator — برای نمایش جهت تغییرات در کنار StatDisplay از TrendIndicator استفاده کنید
• AnimatedNumber — اگر می‌خواهید عدد با انیمیشن شمارشی نمایش داده شود، آن را داخل StatDisplay استفاده کنید