عدد متحرک (AnimatedNumber)

معرفی

کامپوننت AnimatedNumber یک عدد را با انیمیشن شمارش افزایشی (count-up) نمایش می‌دهد. مناسب برای نمایش KPIها، آمار داشبورد، و هر جایی که تغییر عدد باید بصری برجسته شود.

بدون وابستگی به Framer Motion — از requestAnimationFrame خالص استفاده می‌کند.

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

• برای اعداد KPI در داشبورد که تغییرات آن‌ها باید بصری برجسته شود
• در MetricCard و StatDisplay برای جلب توجه به مقادیر مهم
• هنگام بارگذاری اولیه صفحه برای ایجاد حس تعامل

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

• وقتی کاربر نیاز به خواندن دقیق عدد دارد — انیمیشن خوانایی را کاهش می‌دهد
• برای اعداد داخل جدول — حرکت عدد در جدول دیده شدنش را سخت می‌کند

استفاده

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

<AnimatedNumber value={1234} />

مثال‌ها

با فرمت سفارشی

<AnimatedNumber value={98.5} decimals={1} formatFn={(v) => `${v.toFixed(1)}%`} />

با تابع formatNumber از DS

import { AnimatedNumber, formatNumber } from '@parto-system-design/ui'
;<AnimatedNumber value={1500000} formatFn={(v) => formatNumber(Math.round(v), 'fa', 'short')} />

در MetricCard

<MetricCard>
  <MetricCardHeader>
    <MetricCardLabel>مجموع بازدید</MetricCardLabel>
  </MetricCardHeader>
  <MetricCardContent>
    <MetricCardValue>
      <AnimatedNumber value={45230} className="text-stat" />
    </MetricCardValue>
  </MetricCardContent>
</MetricCard>

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

<AnimatedNumber value={100} duration={1000} />

Props

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

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

• انیمیشن در صورت فعال بودن prefers-reduced-motion: reduce غیرفعال می‌شود
• از tabular-nums برای جلوگیری از لرزش layout استفاده می‌کند

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

• StatDisplay — اگر نیاز به نمایش عدد با label و واحد دارید، از StatDisplay استفاده کنید
• MetricCard — اگر نیاز به کارت متریک کامل با sparkline دارید، AnimatedNumber را داخل MetricCardValue استفاده کنید