MotionNumber · MotionText

رقم تتدحرج خاناته كالعجلات، بما فيها الخانات التي تظهر أو تختفي.

الويبReact Nativeالأرقام والنصوص

جرّبه

جارٍ تجهيز المثال…

JavaScript معطّل. الشيفرة أدناه هي المثال الكامل.

App.jsx

import { useState } from 'react';
import { MotionNumber, MotionText, motionTokens } from '@kkwaenggwari/animated-chorus';
import './styles.css';

const formats = {
  plain: {},
  currency: { intl: true, locale: 'en-US', format: { style: 'currency', currency: 'USD' } },
  // Basis points: every preset and every ±1 step shows a different percentage.
  percent: { format: (value) => `${(value / 100).toFixed(2)}%` },
};

const presets = [9, 10, 999, 1000, 12480, 98765];

export default function App({
  mode = 'roll',
  direction = 'auto',
  format = 'currency',
  stagger = 40,
  spring = 'default',
}) {
  const [value, setValue] = useState(1000);
  const [trend, setTrend] = useState('Ready');

  const change = (next) => {
    setTrend(next > value ? 'Rising' : next < value ? 'Falling' : 'Same value');
    setValue(next);
  };

  return (
    <div className="lab">
      <MotionNumber
        className="value"
        value={value}
        mode={mode}
        direction={direction}
        stagger={stagger}
        transition={motionTokens.spring[spring]}
        {...formats[format]}
      />
      <MotionText className="trend">{trend}</MotionText>
      <div className="presets">
        {presets.map((preset) => (
          <button key={preset} onClick={() => change(preset)}>
            {preset}
          </button>
        ))}
      </div>
      <div className="steps">
        <button onClick={() => change(value - 1)}>−1</button>
        <button onClick={() => change(value + 1)}>+1</button>
        <button onClick={() => change(value * 10)}>×10</button>
        <button onClick={() => change(Math.round(value / 10))}>÷10</button>
      </div>
    </div>
  );
}

styles.css

.lab {
  display: grid;
  justify-items: center;
  gap: 14px;
  padding: 32px 20px 28px;
}

.value {
  font:
    800 clamp(44px, 11vw, 80px)/1.05 system-ui,
    sans-serif;
  font-variant-numeric: tabular-nums;
  letter-spacing: -0.03em;
  color: #0e2e24;
}

.trend {
  padding: 4px 12px;
  border-radius: 999px;
  background: #eaf6f0;
  color: #176b52;
  font-weight: 650;
  font-size: 14px;
}

.presets,
.steps {
  display: flex;
  flex-wrap: wrap;
  justify-content: center;
  gap: 8px;
}

.presets button,
.steps button {
  min-width: 56px;
  min-height: 44px;
  padding: 0 14px;
  border: 1px solid #cfe8dc;
  border-radius: 999px;
  background: #fff;
  font:
    600 15px system-ui,
    sans-serif;
  font-variant-numeric: tabular-nums;
  color: #0e2e24;
  cursor: pointer;
}

.steps button {
  background: #f4faf7;
}

.presets button:hover,
.steps button:hover {
  border-color: #176b52;
}

أقصر استخدام

Total.jsx

<MotionNumber value={count} />
<MotionNumber value={total} mode="roll" intl locale="en-US"
  format={{ style: 'currency', currency: 'USD' }} />
<MotionText>{status}</MotionText>

ما يتولّاه عنك

الحمل: 999 → 1,000 يدحرج كل خانة متغيّرة في الاتجاه نفسه، كعدّاد المسافات.
الخانات التي تظهر أو تختفي تتدحرج داخلة أو خارجة من عمودها بدل أن تقفز فجأة.
الفواصل والإشارات ورموز العملات تظهر وتختفي مع الخانة التي تنتمي إليها.
تنزلق الخانات المتبقية إلى مواضعها الجديدة أثناء تدحرجها، فلا ينقسم الرقم أبدًا.
القيمة الجديدة في منتصف الحركة تكمل تمامًا مما على الشاشة.
التنسيق لا يتطلب Intl أبدًا: مرّر نصًا أو دالة format، أو فعّله عبر intl.

استخدمه لـ

مجموع سلة يتغيّر مع إضافة المنتجات.
عدّاد أو نتيجة مباشرة.
رقم في لوحة معلومات يتحدّث كل بضع ثوانٍ.

Props

`MotionNumber`

Prop	النوع	الافتراضي	الوصف
`value`	`number \| bigint \| string`	`—`إلزامي	الرقم، أو نص رقمي نسّقته أنت.
`mode`	`'replace' \| 'roll'`	`'replace'`	ينقل `replace` كل خانة متغيّرة خطوة واحدة؛ ويمر `roll` عبر الأرقام بينها.
`direction`	`'auto' \| 'digit' \| 'up' \| 'down'`	`'auto'`	يتبع `auto` تغيّر المقدار فتتدحرج الخانات المحمولة في اتجاه واحد؛ ويقارن `digit` كل خانة بمفردها.
`stagger`	`number`	`45`	مللي ثوانٍ بين الخانات المتغيّرة، من الآحاد إلى الخارج. والموجة كلها محدودة المدة.
`format`	`(value) => string \| Intl.NumberFormatOptions`		دالة تعيد النص المراد عرضه، أو خيارات `Intl.NumberFormat` (مع `intl`).
`intl`	`boolean`	`false`	استخدم `Intl.NumberFormat` المدمج. معطّل افتراضيًا كي لا تحتاج أي بيئة تشغيل إلى `Intl`.
`locale`	`string \| string[]`		اللغة المحلية لـ `intl`.
`prefix`	`string`		نص قبل الرقم.
`suffix`	`string`		نص بعد الرقم.
`transition`	`Transition`	`spring`	منحنى توقيت `{ duration, easing }` أو نابض `{ tempo: 'spring', spring }`. تحتفظ النوابض بزخمها عند المقاطعة.
`onMotionComplete`	`(value) => void`		يعمل مع القيمة بعد استقرار الخانات.

`MotionText`

Prop	النوع	الافتراضي	الوصف
`children`	`ReactNode`		النص المراد عرضه.
`as`	`element`	`'span'`	العنصر المراد عرضه.
`transition`	`Transition`	`spring`	منحنى توقيت `{ duration, easing }` أو نابض `{ tempo: 'spring', spring }`. تحتفظ النوابض بزخمها عند المقاطعة.
`onMotionComplete`	`(text) => void`		يعمل حين تستقر الحركة.

تذهب props الأخرى إلى العنصر المعروض، فتعمل className وstyle ومعالجات الأحداث كالمعتاد.

الويب وReact Native

على الويب كل خانة كومة صغيرة من الرموز تشغّلها Web Animations API، ويبقى النص قابلًا للتحديد. يحرّك MotionText أي نص: النص الرقمي يتدحرج خانةً خانة، والنص الآخر يتبدّل.

في React Native يبقى الرقم Text حقيقيًا للتخطيط والتحديد وسهولة الوصول، بما في ذلك الالتفاف وnumberOfLines؛ وتتحرك الرموز على المشغّل الأصلي.