MotionNumber · MotionText

Con số có các chữ số cuộn như bánh xe, kể cả chữ số xuất hiện hay biến mất.

WebReact NativeSố và văn bản

Thử ngay

Đang chuẩn bị ví dụ…

JavaScript đang tắt. Đoạn mã bên dưới là ví dụ đầy đủ.

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;
}

Cách dùng ngắn nhất

Total.jsx

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

Những gì nó xử lý giúp bạn

Nhớ sang hàng: 999 → 1,000 cuộn mọi chữ số thay đổi theo cùng một hướng, như đồng hồ công-tơ-mét.
Chữ số xuất hiện hay biến mất sẽ cuộn vào hoặc ra khỏi cột của chính nó thay vì bật ra đột ngột.
Dấu phân cách, dấu và ký hiệu tiền tệ hiện ra rồi mờ đi cùng chữ số mà chúng thuộc về.
Các chữ số còn lại trượt sang vị trí mới trong lúc cuộn, nên con số không bao giờ bị tách rời.
Giá trị mới giữa chừng tiếp tục đúng từ những gì đang trên màn hình.
Định dạng không bao giờ bắt buộc Intl: truyền văn bản hoặc hàm format, hoặc chủ động bật bằng intl.

Dùng cho

Tổng giỏ hàng thay đổi khi thêm sản phẩm.
Bộ đếm hoặc điểm số trực tiếp.
Chỉ số bảng điều khiển làm mới sau vài giây.

Props

`MotionNumber`

Prop	Kiểu	Mặc định	Mô tả
`value`	`number \| bigint \| string`	`—`bắt buộc	Con số, hoặc văn bản số đã được bên gọi định dạng.
`mode`	`'replace' \| 'roll'`	`'replace'`	`replace` dịch mỗi chữ số thay đổi một bước; `roll` đi qua các chữ số ở giữa.
`direction`	`'auto' \| 'digit' \| 'up' \| 'down'`	`'auto'`	`auto` theo sự thay đổi độ lớn để phần nhớ cuộn một hướng; `digit` so sánh từng chữ số riêng.
`stagger`	`number`	`45`	Mili giây giữa các chữ số thay đổi, từ hàng đơn vị ra ngoài. Toàn bộ gợn sóng có giới hạn.
`format`	`(value) => string \| Intl.NumberFormatOptions`		Hàm trả về văn bản để hiển thị, hoặc tùy chọn `Intl.NumberFormat` (với `intl`).
`intl`	`boolean`	`false`	Dùng `Intl.NumberFormat` có sẵn. Mặc định tắt để không runtime nào bắt buộc có `Intl`.
`locale`	`string \| string[]`		Locale cho `intl`.
`prefix`	`string`		Văn bản trước con số.
`suffix`	`string`		Văn bản sau con số.
`transition`	`Transition`	`spring`	Đường cong timing `{ duration, easing }` hoặc lò xo `{ tempo: 'spring', spring }`. Lò xo giữ đà khi bị ngắt.
`onMotionComplete`	`(value) => void`		Chạy với giá trị khi các chữ số đã dừng.

`MotionText`

Prop	Kiểu	Mặc định	Mô tả
`children`	`ReactNode`		Văn bản để hiển thị.
`as`	`element`	`'span'`	Phần tử được render.
`transition`	`Transition`	`spring`	Đường cong timing `{ duration, easing }` hoặc lò xo `{ tempo: 'spring', spring }`. Lò xo giữ đà khi bị ngắt.
`onMotionComplete`	`(text) => void`		Chạy khi chuyển động dừng hẳn.

Các props khác được chuyển tới phần tử được render, nên className, style và trình xử lý sự kiện hoạt động như bình thường.

Web và React Native

Trên web, mỗi chữ số là một chồng glyph nhỏ do Web Animations API phát, và văn bản vẫn chọn được. MotionText tạo hoạt ảnh cho mọi văn bản: văn bản số cuộn theo từng chữ số, văn bản khác thì hoán đổi.

Trên React Native, con số vẫn là Text thật cho bố cục, việc chọn và trợ năng, kể cả xuống dòng và numberOfLines; các glyph chuyển động bằng native driver.