عدد متحرک (AnimatedNumber)

معرفی

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

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

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

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

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

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

زمین بازی

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

استفاده

import { AnimatedNumber } from '@partodata/ui'

<AnimatedNumber value={1234} />

مثال‌ها

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

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

با تابع formatLargeNumber از DS

import { AnimatedNumber, formatLargeNumber } from '@partodata/ui'
;<AnimatedNumber value={1500000} formatFn={(v) => formatLargeNumber(Math.round(v), 'fa')} />

در 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 را می‌گذارد، ولی روی این ادعا حساب نکنید: فونت یکان بخ ویژگی tnum ندارد (فهرست featureهایش aalt, fina, init, locl, medi, pnum, rlig, salt, ss01… است) و عرض ارقام فارسی‌اش از 260 تا 700 یونیت در em نوسان دارد. پس عدد در حال شمارش عرضش عوض می‌شود؛ اگر پرش چیدمان مهم است، ظرف را با min-w-* یا w-* تثبیت کنید.

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

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