API 參考

@kkwaenggwari/animated-chorus 的所有匯出，以及它們的 props、型別與預設值。Web 與 React Native 使用相同的名稱。

篩選17 個 API

數字與文字

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`		動態停穩時執行。

元件頁面與工作台

MotionStream

以穩定節奏顯示串流文字，內容一次湧入時也能追上。

Prop	型別	預設值	說明
`text`	`string`	`—`必填	目前為止的文字。增加的文字以穩定節奏顯示；被改寫時從共同的開頭繼續。
`speed`	`number`	`90`	基本顯示速度，單位為每秒字元數。
`catchUp`	`number`	`900`	積壓的內容會加速顯示，在大約這麼多毫秒內全部呈現。
`initial`	`boolean`	`false`	掛載時已有的文字也逐步顯示（否則立即顯示）。
`effect`	`'fade' \| 'none'`	`'fade'`	`fade` 讓新字元淡入；`none` 直接顯示。
`children`	`(visible: string) => ReactNode`		接收依節奏輸出之文字的函式，例如用來渲染 Markdown。
`as`	`element`	`'span'`	要渲染的元素。
`onMotionComplete`	`(text) => void`		每當顯示進度追上 `text` 時執行。

元件頁面與工作台

內容與尺寸

MotionSwap

元素改變尺寸時，內容交叉淡入淡出。

Prop	型別	預設值	說明
`value`	`unknown`		內容的識別；新的值會觸發切換。純文字子元素本身就是識別。
`children`	`ReactNode`		內容。
`as`	`element`	`'span'`	要渲染的元素。
`inline`	`boolean`	`as === 'span'`	`true` 依內容決定尺寸（標籤、圖示）；`false` 撐滿父元素寬度並為高度加上動畫。
`align`	`'start' \| 'center' \| 'end'`	`'center'`	尺寸改變時內容所在的位置。
`effect`	`'fade' \| 'up' \| 'down' \| 'scale'`	`'fade'`	內容如何進出：`up` 上升，`down` 下降，`scale` 放大。
`transition`	`Transition`	`spring`	時間曲線 `{ duration, easing }` 或彈簧 `{ tempo: 'spring', spring }`。彈簧被中斷時會保留動量。
`onMotionComplete`	`(value) => void`		動態停穩時執行。

元件頁面與工作台

MotionHeight

讓高度隨內容以動畫過渡：收合、展開與內容變化。

Prop	型別	預設值	說明
`open`	`boolean`	`true`	`false` 收合到零高度；內容保持掛載但隱藏且無法互動。
`children`	`ReactNode`		內容。
`as`	`element`	`'div'`	要渲染的元素。
`transition`	`Transition`	`spring`	時間曲線 `{ duration, easing }` 或彈簧 `{ tempo: 'spring', spring }`。彈簧被中斷時會保留動量。
`onMotionComplete`	`(open) => void`		高度停穩後，帶著 `open` 執行。

元件頁面與工作台

MotionPresence

在進場與離場動畫期間保持內容掛載。

Prop	型別	預設值	說明
`present`	`boolean`	`—`必填	顯示或隱藏內容。用它來取代卸載。
`enter`	`Pose`	`{ opacity: 1, translateY: 0 }`	靜止時的姿態。
`exit`	`Pose`	`{ opacity: 0, translateY: -12 }`	內容離場以及進場時使用的姿態。
`as`	`element`	`'div'`	要渲染的元素。
`transition`	`Transition`	`spring`	時間曲線 `{ duration, easing }` 或彈簧 `{ tempo: 'spring', spring }`。彈簧被中斷時會保留動量。
`onExitComplete`	`() => void`		內容離場並被移除後執行。

元件頁面與工作台

選擇與翻頁

MotionHighlight

由資料產生的項目，以及一個移向選取項目的醒目標示。

Prop	型別	預設值	說明
`items`	`readonly T[]`	`—`必填	你的資料陣列。
`value`	`key \| null`	`—`必填	醒目標示項目的 key；`null` 會隱藏醒目標示。
`onValueChange`	`(key, item) => void`		項目被按下時，帶著 key 與該項目執行。
`getKey`	`(item) => string \| number`	`item.id`	為項目回傳唯一且穩定的 key。預設為 `item.id`，字串與數字則為它本身。
`renderItem`	`(item, { selected, index }) => ReactNode`	`item.label`	繪製一個項目；會收到它是否被選取。
`hover`	`boolean`	`false`	在項目上跟隨指標，離開時回到 `value`（Web）。
`itemAs`	`element`	`'button'`	每個項目使用的元素。
`itemClassName`	`string`		每個項目元素的 class；`itemStyle` 設定其行內樣式。
`highlightClassName`	`string`		醒目標示的 class；`highlightStyle` 設定其行內樣式。
`transition`	`Transition`	`spring`	時間曲線 `{ duration, easing }` 或彈簧 `{ tempo: 'spring', spring }`。彈簧被中斷時會保留動量。

元件頁面與工作台

MotionPager

由資料產生、可滑動的頁面。

Prop	型別	預設值	說明
`items`	`readonly T[]`	`—`必填	你的資料陣列。
`index`	`number`		顯示的頁面。省略時由翻頁器自行管理。
`defaultIndex`	`number`	`0`	`index` 不受控時的起始頁面。
`onIndexChange`	`(index, item) => void`		滑動、按鍵或滾輪手勢停穩後，立即帶著索引與該項目執行。
`getKey`	`(item) => string \| number`	`item.id`	為項目回傳唯一且穩定的 key。預設為 `item.id`，字串與數字則為它本身。
`renderItem`	`(item, { index, active }) => ReactNode`	`item.label`	繪製一頁；會收到它的索引以及是否為目前頁面。
`gap`	`number`	`0`	頁面之間的間距，單位為像素。
`itemClassName`	`string`		每個項目元素的 class；`itemStyle` 設定其行內樣式。
`transition`	`Transition`	`spring`	時間曲線 `{ duration, easing }` 或彈簧 `{ tempo: 'spring', spring }`。彈簧被中斷時會保留動量。

元件頁面與工作台

清單

MotionList

由資料產生、具 key、只為變動項目加上動畫的清單。

Prop	型別	預設值	說明
`items`	`readonly T[]`	`—`必填	你的資料陣列。
`getKey`	`(item) => string \| number`	`item.id`	為項目回傳唯一且穩定的 key。預設為 `item.id`，字串與數字則為它本身。
`renderItem`	`(item, index) => ReactNode`	`item.label`	繪製一個項目。
`as`	`element`	`'div'`	要渲染的元素。
`itemAs`	`element`	`'li' \| 'div'`	每個項目使用的元素。
`itemClassName`	`string`		每個項目元素的 class；`itemStyle` 設定其行內樣式。
`effect`	`'rise' \| 'fade' \| 'scale' \| 'slide'`	`'rise'`	項目如何進出。
`distance`	`number`	`16`	`rise` 與 `slide` 的移動距離，單位為像素。
`stagger`	`number`	`40`	進場項目之間的毫秒間隔。
`order`	`'forward' \| 'reverse'`	`'forward'`	錯開的方向。
`present`	`boolean`	`true`	`false` 在保留版面的同時讓所有項目離場；`true` 讓它們回來。
`initial`	`boolean`	`true`	清單掛載時播放進場動畫。
`playKey`	`string \| number`		改變它會重播進場動畫。
`transition`	`Transition`	`spring`	進出場項目的轉場。
`layoutTransition`	`Transition`	`spring`	滑向新位置之項目的轉場。

元件頁面與工作台

MotionReorder

拖曳以重新排序清單或格狀排列，支援鍵盤移動。

Prop	型別	預設值	說明
`items`	`readonly T[]`		由你控制順序時的項目。
`defaultItems`	`readonly T[]`	`[]`	由元件保存順序時的初始項目。
`onItemsChange`	`(items, { reason, key }) => void`		帶著新的順序，以及變化來自拖曳、放下或鍵盤執行。
`getKey`	`(item) => string \| number`	`item`	為項目回傳唯一的 key。預設為項目本身。
`renderItem`	`(item, { index, dragging }) => ReactNode`	`item.label`	繪製一個項目；會收到它的索引以及是否正被拖曳。
`reorder`	`'live' \| 'drop'`	`'live'`	`live` 在拖曳時移動其他項目；`drop` 等到放下才移動。
`layout`	`'list' \| 'grid'`	`'grid'`	`list` 或 `grid`。
`columns`	`number`	`3`	格狀排列的欄數。
`gap`	`number`	`12`	項目之間的間距，單位為像素。
`disabled`	`boolean`	`false`	關閉拖曳。
`duration`	`number`	`260`	其他項目讓開時的毫秒時長。
`itemClassName`	`string`		每個項目元素的 class；`itemStyle` 設定其行內樣式。

元件頁面與工作台

手勢

MotionSwipe

水平滑動會顯示操作按鈕、也能被滑走的列。

Prop	型別	預設值	說明
`children`	`ReactNode`		列的內容。
`startActions`	`ReactNode`		把列往結尾方向拖曳時，在行內開頭一側顯示。
`endActions`	`ReactNode`		把列往開頭方向拖曳時，在行內結尾一側顯示。
`dismiss`	`'start' \| 'end' \| 'both'`		長距離滑動或快速甩出會移除該列的方向。
`onDismiss`	`(side) => void`		列滑出並收起後執行；請在這裡把該項目從資料中移除。
`onOpenChange`	`(side \| null) => void`		帶著展開的那一側執行，列收起時為 `null`。
`disabled`	`boolean`	`false`	關閉滑動。
`contentClassName`	`string`		列內容的 class；`contentStyle` 設定其行內樣式。
`transition`	`Transition`	`spring`	時間曲線 `{ duration, easing }` 或彈簧 `{ tempo: 'spring', spring }`。彈簧被中斷時會保留動量。

元件頁面與工作台

MotionHold

長按以確認；提早放開會倒轉回去。

Prop	型別	預設值	說明
`children`	`ReactNode`		按鈕的標籤。
`onConfirm`	`() => void`		長按完成時執行一次。
`duration`	`number`	`1200`	需要按住的毫秒數。
`disabled`	`boolean`	`false`	停用按鈕。
`fillClassName`	`string`		逐漸增加之填色的 class；`fillStyle` 設定其行內樣式。

元件頁面與工作台

浮層

MotionSheet

有段位的底部面板、頂部面板或側邊抽屜。

Prop	型別	預設值	說明
`open`	`boolean`	`false`	是否顯示面板。
`onOpenChange`	`(open) => void`		面板被拖曳、點擊或按 Escape 關閉時，帶著 `false` 執行。
`detents`	`(number \| 'content')[]`	`['content']`	停靠尺寸：螢幕比例、像素或 `'content'`。
`detent`	`number`		受控的段位索引。
`defaultDetent`	`number`	`0`	未指定 `detent` 開啟時使用的段位索引。
`onDetentChange`	`(index) => void`		帶著面板停穩時所在段位的索引執行。
`side`	`'bottom' \| 'top' \| 'start' \| 'end'`	`'bottom'`	面板出現的邊緣。
`modal`	`boolean`	`true`	加入背景遮罩、把焦點限制在內部，並讓頁面無法互動。
`dismissible`	`boolean`	`true`	拖過最小段位、點擊背景遮罩或按 Escape 都能關閉它。
`backdropClassName`	`string`		背景遮罩的 class；`backdropStyle` 設定其行內樣式。
`transition`	`Transition`	`spring`	時間曲線 `{ duration, easing }` 或彈簧 `{ tempo: 'spring', spring }`。彈簧被中斷時會保留動量。

元件頁面與工作台

MotionZoom

從原位放大到填滿螢幕的圖片。

Prop	型別	預設值	說明
`src`	`string`		在原位顯示的圖片。
`zoomSrc`	`string`		載入完成後顯示的大圖；請維持相同的長寬比。
`margin`	`number`	`24`	放大後圖片周圍保留的空間，單位為像素。
`disabled`	`boolean`	`false`	關閉縮放。
`onZoomChange`	`(zoomed) => void`		放大時帶著 `true`、關閉時帶著 `false` 執行。
`backdropStyle`	`CSSProperties`		背景遮罩的行內樣式。
`transition`	`Transition`	`spring`	時間曲線 `{ duration, easing }` 或彈簧 `{ tempo: 'spring', spring }`。彈簧被中斷時會保留動量。

元件頁面與工作台

進度

ProgressBar

支援不確定狀態的受控進度條。

Prop	型別	預設值	說明
`value`	`number \| null`		從 `0` 到 `max` 的進度；`null` 表示不確定。
`max`	`number`	`100`	代表完成的值。
`color`	`string`	`'currentColor'`	填色顏色。
`trackColor`	`string`	`'#e7ece9'`	軌道顏色。
`thickness`	`number`	`8`	線條粗細，單位為像素。
`direction`	`'ltr' \| 'rtl'`	`'ltr'`	從左（`ltr`）或從右（`rtl`）開始填滿。
`transition`	`Transition`	`spring`	時間曲線 `{ duration, easing }` 或彈簧 `{ tempo: 'spring', spring }`。彈簧被中斷時會保留動量。

元件頁面與工作台

ProgressRing

支援不確定狀態的受控進度環。

Prop	型別	預設值	說明
`value`	`number \| null`		從 `0` 到 `max` 的進度；`null` 表示不確定。
`max`	`number`	`100`	代表完成的值。
`size`	`number`	`96`	直徑，單位為像素。
`thickness`	`number`	`8`	圓環粗細，單位為像素。
`color`	`string`	`'currentColor'`	弧線顏色。
`trackColor`	`string`	`'#e7ece9'`	軌道顏色。
`children`	`ReactNode`		顯示在中間的標籤。
`transition`	`Transition`	`spring`	時間曲線 `{ duration, easing }` 或彈簧 `{ tempo: 'spring', spring }`。彈簧被中斷時會保留動量。

元件頁面與工作台

轉場

motionTokens

可用於任何 transition prop 的現成值。

Prop	型別	預設值	說明
`duration`	`{ instant, fast, normal, slow }`	`0 · 140 · 280 · 520`	時長，單位為毫秒。
`easing`	`{ ease, easeOut, expoOut, backOut }`	`Transition`	具有時長與具名曲線的時間轉場。
`spring`	`{ quick, basic, gentle, bouncy }`	`Transition`	彈簧轉場，從快速紮實到柔和彈跳。

轉場

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