Tham chiếu API

Mọi export của @kkwaenggwari/animated-chorus kèm props, kiểu và giá trị mặc định. Cùng tên hoạt động trên web và React Native.

Bộ lọc17 API

Số và văn bản

MotionNumber

Con số có các chữ số cuộn như bánh xe.

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.

Trang component và bàn làm việc

MotionText

Văn bản có hoạt ảnh khi thay đổi: văn bản số cuộn theo từng chữ số, văn bản khác thì hoán đổi.

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.

Trang component và bàn làm việc

MotionStream

Văn bản truyền dần hiện ra với nhịp đều, đuổi kịp khi dữ liệu dồn tới.

Prop	Kiểu	Mặc định	Mô tả
`text`	`string`	`—`bắt buộc	Văn bản đến hiện tại. Văn bản dài thêm được hiện ra với nhịp đều; bản viết lại tiếp tục từ phần đầu chung.
`speed`	`number`	`90`	Tốc độ hiển thị cơ bản tính bằng ký tự mỗi giây.
`catchUp`	`number`	`900`	Phần tồn đọng được tăng tốc để hiện ra trong khoảng chừng ấy mili giây.
`initial`	`boolean`	`false`	Hiển thị dần cả văn bản có sẵn khi mount (nếu không, nó hiện ngay).
`effect`	`'fade' \| 'none'`	`'fade'`	`fade` làm ký tự mới hiện dần; `none` hiện chúng ngay.
`children`	`(visible: string) => ReactNode`		Hàm nhận văn bản đã điều nhịp, ví dụ để render Markdown.
`as`	`element`	`'span'`	Phần tử được render.
`onMotionComplete`	`(text) => void`		Chạy mỗi khi phần hiển thị đuổi kịp `text`.

Trang component và bàn làm việc

Nội dung và kích thước

MotionSwap

Nội dung chuyển mờ chéo trong khi phần tử đổi kích thước.

Prop	Kiểu	Mặc định	Mô tả
`value`	`unknown`		Danh tính của nội dung; giá trị mới sẽ hoán đổi. Children là văn bản thường thì chính là danh tính.
`children`	`ReactNode`		Nội dung.
`as`	`element`	`'span'`	Phần tử được render.
`inline`	`boolean`	`as === 'span'`	`true` lấy kích thước theo nội dung (nhãn, biểu tượng); `false` lấp đầy chiều rộng phần tử cha và tạo hoạt ảnh cho chiều cao.
`align`	`'start' \| 'center' \| 'end'`	`'center'`	Vị trí của nội dung trong lúc kích thước thay đổi.
`effect`	`'fade' \| 'up' \| 'down' \| 'scale'`	`'fade'`	Cách nội dung vào và ra: `up` đi lên, `down` rơi xuống, `scale` lớn dần.
`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 khi chuyển động dừng hẳn.

Trang component và bàn làm việc

MotionHeight

Tạo hoạt ảnh chiều cao theo nội dung: thu gọn, mở rộng và thay đổi nội dung.

Prop	Kiểu	Mặc định	Mô tả
`open`	`boolean`	`true`	`false` thu về chiều cao bằng không; nội dung vẫn được gắn nhưng bị ẩn và vô hiệu.
`children`	`ReactNode`		Nội dung.
`as`	`element`	`'div'`	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`	`(open) => void`		Chạy với `open` khi chiều cao đã dừng.

Trang component và bàn làm việc

MotionPresence

Giữ nội dung được gắn trong lúc nó hoạt ảnh vào và ra.

Prop	Kiểu	Mặc định	Mô tả
`present`	`boolean`	`—`bắt buộc	Hiện hoặc ẩn nội dung. Đổi giá trị này thay vì unmount.
`enter`	`Pose`	`{ opacity: 1, translateY: 0 }`	Pose khi nghỉ.
`exit`	`Pose`	`{ opacity: 0, translateY: -12 }`	Pose mà nội dung rời đi và đi vào từ đó.
`as`	`element`	`'div'`	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.
`onExitComplete`	`() => void`		Chạy sau khi nội dung đã rời đi và bị gỡ.

Trang component và bàn làm việc

Lựa chọn và phân trang

MotionHighlight

Các mục từ dữ liệu với một điểm nhấn di chuyển đến mục được chọn.

Prop	Kiểu	Mặc định	Mô tả
`items`	`readonly T[]`	`—`bắt buộc	Mảng dữ liệu của bạn.
`value`	`key \| null`	`—`bắt buộc	Key của mục được nhấn mạnh; `null` ẩn điểm nhấn.
`onValueChange`	`(key, item) => void`		Chạy với key và mục khi một mục được nhấn.
`getKey`	`(item) => string \| number`	`item.id`	Trả về key duy nhất, ổn định cho một mục. Mặc định là `item.id`, hoặc chính mục đó với chuỗi và số.
`renderItem`	`(item, { selected, index }) => ReactNode`	`item.label`	Vẽ một mục; nhận thông tin mục đó có được chọn hay không.
`hover`	`boolean`	`false`	Bám theo con trỏ trên các mục và quay về `value` khi rời đi (web).
`itemAs`	`element`	`'button'`	Phần tử cho từng mục.
`itemClassName`	`string`		Class cho từng phần tử mục; `itemStyle` đặt style nội tuyến của nó.
`highlightClassName`	`string`		Class cho điểm nhấn; `highlightStyle` đặt style nội tuyến của nó.
`transition`	`Transition`	`spring`	Đường cong timing `{ duration, easing }` hoặc lò xo `{ tempo: 'spring', spring }`. Lò xo giữ đà khi bị ngắt.

Trang component và bàn làm việc

MotionPager

Các trang vuốt được từ dữ liệu.

Prop	Kiểu	Mặc định	Mô tả
`items`	`readonly T[]`	`—`bắt buộc	Mảng dữ liệu của bạn.
`index`	`number`		Trang đang hiển thị. Bỏ trống để pager tự quản lý.
`defaultIndex`	`number`	`0`	Trang bắt đầu khi `index` không được kiểm soát.
`onIndexChange`	`(index, item) => void`		Chạy với index và mục ngay khi cử chỉ vuốt, phím hoặc con lăn dừng lại.
`getKey`	`(item) => string \| number`	`item.id`	Trả về key duy nhất, ổn định cho một mục. Mặc định là `item.id`, hoặc chính mục đó với chuỗi và số.
`renderItem`	`(item, { index, active }) => ReactNode`	`item.label`	Vẽ một trang; nhận index của nó và việc nó có đang hiện hành không.
`gap`	`number`	`0`	Khoảng cách giữa các trang tính bằng pixel.
`itemClassName`	`string`		Class cho từng phần tử mục; `itemStyle` đặt style nội tuyến của nó.
`transition`	`Transition`	`spring`	Đường cong timing `{ duration, easing }` hoặc lò xo `{ tempo: 'spring', spring }`. Lò xo giữ đà khi bị ngắt.

Trang component và bàn làm việc

Danh sách

MotionList

Danh sách có key từ dữ liệu, chỉ tạo hoạt ảnh cho phần thay đổi.

Prop	Kiểu	Mặc định	Mô tả
`items`	`readonly T[]`	`—`bắt buộc	Mảng dữ liệu của bạn.
`getKey`	`(item) => string \| number`	`item.id`	Trả về key duy nhất, ổn định cho một mục. Mặc định là `item.id`, hoặc chính mục đó với chuỗi và số.
`renderItem`	`(item, index) => ReactNode`	`item.label`	Vẽ một mục.
`as`	`element`	`'div'`	Phần tử được render.
`itemAs`	`element`	`'li' \| 'div'`	Phần tử cho từng mục.
`itemClassName`	`string`		Class cho từng phần tử mục; `itemStyle` đặt style nội tuyến của nó.
`effect`	`'rise' \| 'fade' \| 'scale' \| 'slide'`	`'rise'`	Cách các mục vào và ra.
`distance`	`number`	`16`	Quãng di chuyển của `rise` và `slide` tính bằng pixel.
`stagger`	`number`	`40`	Mili giây giữa các mục đi vào.
`order`	`'forward' \| 'reverse'`	`'forward'`	Hướng so le.
`present`	`boolean`	`true`	`false` tạo hoạt ảnh đưa mọi mục ra nhưng giữ bố cục; `true` đưa chúng trở lại.
`initial`	`boolean`	`true`	Phát hoạt ảnh vào khi danh sách được mount.
`playKey`	`string \| number`		Thay đổi giá trị này sẽ phát lại hoạt ảnh vào.
`transition`	`Transition`	`spring`	Chuyển tiếp cho mục đi vào và rời đi.
`layoutTransition`	`Transition`	`spring`	Chuyển tiếp cho mục lướt đến vị trí mới.

Trang component và bàn làm việc

MotionReorder

Kéo để sắp xếp lại danh sách hoặc lưới, có di chuyển bằng bàn phím.

Prop	Kiểu	Mặc định	Mô tả
`items`	`readonly T[]`		Các mục, khi bạn kiểm soát thứ tự.
`defaultItems`	`readonly T[]`	`[]`	Các mục ban đầu, khi component tự giữ thứ tự.
`onItemsChange`	`(items, { reason, key }) => void`		Chạy với thứ tự mới và cho biết nó đến từ kéo, thả hay bàn phím.
`getKey`	`(item) => string \| number`	`item`	Trả về key duy nhất cho một mục. Mặc định là chính mục đó.
`renderItem`	`(item, { index, dragging }) => ReactNode`	`item.label`	Vẽ một mục; nhận index của nó và việc nó có đang được kéo không.
`reorder`	`'live' \| 'drop'`	`'live'`	`live` dời các mục khác trong lúc kéo; `drop` chờ đến khi thả.
`layout`	`'list' \| 'grid'`	`'grid'`	`list` hoặc `grid`.
`columns`	`number`	`3`	Số cột trong lưới.
`gap`	`number`	`12`	Khoảng cách giữa các mục tính bằng pixel.
`disabled`	`boolean`	`false`	Tắt kéo.
`duration`	`number`	`260`	Mili giây cho các mục tránh đường.
`itemClassName`	`string`		Class cho từng phần tử mục; `itemStyle` đặt style nội tuyến của nó.

Trang component và bàn làm việc

Cử chỉ

MotionSwipe

Hàng hiện thao tác khi vuốt ngang và có thể vuốt đi.

Prop	Kiểu	Mặc định	Mô tả
`children`	`ReactNode`		Nội dung của hàng.
`startActions`	`ReactNode`		Hiện ở đầu dòng khi hàng bị kéo về phía cuối.
`endActions`	`ReactNode`		Hiện ở cuối dòng khi hàng bị kéo về phía đầu.
`dismiss`	`'start' \| 'end' \| 'both'`		Các phía mà vuốt dài hoặc hất sẽ xóa hàng.
`onDismiss`	`(side) => void`		Chạy sau khi hàng trượt ra và thu gọn; hãy xóa mục khỏi dữ liệu của bạn tại đây.
`onOpenChange`	`(side \| null) => void`		Chạy với phía đang mở, hoặc `null` khi hàng đóng lại.
`disabled`	`boolean`	`false`	Tắt vuốt.
`contentClassName`	`string`		Class cho nội dung hàng; `contentStyle` đặt style nội tuyến của nó.
`transition`	`Transition`	`spring`	Đường cong timing `{ duration, easing }` hoặc lò xo `{ tempo: 'spring', spring }`. Lò xo giữ đà khi bị ngắt.

Trang component và bàn làm việc

MotionHold

Nhấn giữ để xác nhận; thả sớm sẽ tua ngược.

Prop	Kiểu	Mặc định	Mô tả
`children`	`ReactNode`		Nhãn của nút.
`onConfirm`	`() => void`		Chạy khi việc nhấn giữ hoàn tất.
`duration`	`number`	`1200`	Số mili giây cần giữ.
`disabled`	`boolean`	`false`	Tắt nút.
`fillClassName`	`string`		Class cho phần tô đang tăng; `fillStyle` đặt style nội tuyến của nó.

Trang component và bàn làm việc

Lớp phủ

MotionSheet

Sheet đáy, sheet đỉnh hoặc ngăn kéo bên với các điểm dừng.

Prop	Kiểu	Mặc định	Mô tả
`open`	`boolean`	`false`	Sheet có đang hiển thị hay không.
`onOpenChange`	`(open) => void`		Chạy với `false` khi sheet bị đóng bằng kéo, chạm hoặc Escape.
`detents`	`(number \| 'content')[]`	`['content']`	Kích thước khi nghỉ: tỉ lệ màn hình, pixel hoặc `'content'`.
`detent`	`number`		Index điểm dừng được kiểm soát.
`defaultDetent`	`number`	`0`	Index điểm dừng dùng khi mở mà không có `detent`.
`onDetentChange`	`(index) => void`		Chạy với index của điểm dừng nơi sheet dừng lại.
`side`	`'bottom' \| 'top' \| 'start' \| 'end'`	`'bottom'`	Cạnh mà sheet xuất hiện từ đó.
`modal`	`boolean`	`true`	Thêm lớp nền, giữ focus bên trong và làm trang vô hiệu.
`dismissible`	`boolean`	`true`	Kéo quá điểm dừng nhỏ nhất, lớp nền và Escape sẽ đóng nó.
`backdropClassName`	`string`		Class cho lớp nền; `backdropStyle` đặt style nội tuyến của nó.
`transition`	`Transition`	`spring`	Đường cong timing `{ duration, easing }` hoặc lò xo `{ tempo: 'spring', spring }`. Lò xo giữ đà khi bị ngắt.

Trang component và bàn làm việc

MotionZoom

Ảnh phóng to từ vị trí của nó cho đến khi lấp đầy màn hình.

Prop	Kiểu	Mặc định	Mô tả
`src`	`string`		Ảnh hiển thị tại chỗ.
`zoomSrc`	`string`		Ảnh lớn hơn hiển thị khi đã tải xong; hãy giữ cùng tỉ lệ khung hình.
`margin`	`number`	`24`	Khoảng trống quanh ảnh phóng to tính bằng pixel.
`disabled`	`boolean`	`false`	Tắt phóng to.
`onZoomChange`	`(zoomed) => void`		Chạy với `true` khi phóng to và `false` khi đóng.
`backdropStyle`	`CSSProperties`		Style nội tuyến cho lớp nền.
`transition`	`Transition`	`spring`	Đường cong timing `{ duration, easing }` hoặc lò xo `{ tempo: 'spring', spring }`. Lò xo giữ đà khi bị ngắt.

Trang component và bàn làm việc

Tiến độ

ProgressBar

Đường tiến độ có kiểm soát với trạng thái không xác định.

Prop	Kiểu	Mặc định	Mô tả
`value`	`number \| null`		Tiến độ từ `0` đến `max`; `null` là không xác định.
`max`	`number`	`100`	Giá trị nghĩa là hoàn tất.
`color`	`string`	`'currentColor'`	Màu tô.
`trackColor`	`string`	`'#e7ece9'`	Màu rãnh.
`thickness`	`number`	`8`	Độ dày đường tính bằng pixel.
`direction`	`'ltr' \| 'rtl'`	`'ltr'`	Tô từ trái (`ltr`) hoặc từ phải (`rtl`).
`transition`	`Transition`	`spring`	Đường cong timing `{ duration, easing }` hoặc lò xo `{ tempo: 'spring', spring }`. Lò xo giữ đà khi bị ngắt.

Trang component và bàn làm việc

ProgressRing

Vòng tiến độ có kiểm soát với trạng thái không xác định.

Prop	Kiểu	Mặc định	Mô tả
`value`	`number \| null`		Tiến độ từ `0` đến `max`; `null` là không xác định.
`max`	`number`	`100`	Giá trị nghĩa là hoàn tất.
`size`	`number`	`96`	Đường kính tính bằng pixel.
`thickness`	`number`	`8`	Độ dày vòng tính bằng pixel.
`color`	`string`	`'currentColor'`	Màu cung.
`trackColor`	`string`	`'#e7ece9'`	Màu rãnh.
`children`	`ReactNode`		Nhãn hiển thị ở giữa.
`transition`	`Transition`	`spring`	Đường cong timing `{ duration, easing }` hoặc lò xo `{ tempo: 'spring', spring }`. Lò xo giữ đà khi bị ngắt.

Trang component và bàn làm việc

Chuyển tiếp

motionTokens

Giá trị có sẵn cho mọi prop transition.

Prop	Kiểu	Mặc định	Mô tả
`duration`	`{ instant, fast, normal, slow }`	`0 · 140 · 280 · 520`	Thời lượng tính bằng mili giây.
`easing`	`{ ease, easeOut, expoOut, backOut }`	`Transition`	Chuyển tiếp timing với thời lượng và đường cong có tên.
`spring`	`{ quick, basic, gentle, bouncy }`	`Transition`	Chuyển tiếp lò xo, từ nhanh và chắc đến êm và nảy.

Chuyển tiếp

App.jsx

// Web and React Native: the same import.
import { MotionNumber, MotionList } from '@kkwaenggwari/animated-chorus';

export function Score({ points, players }) {
  return (
    <>
      <MotionNumber value={points} />
      <MotionList items={players} renderItem={(player) => player.name} />
    </>
  );
}