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