跳到正文
目录与搜索
⌘K

原语 / Animate UI

Motion Grid · Animate UI

一格一帧播放动画的点阵,用来做加载与状态指示。

安装

自有原语直接来自 @animate-ui/react,不依赖 Radix UI、Base UI 或 React Aria;装上包即可使用。

终端
bun add @animate-ui/react motion

用法

直接从 @animate-ui/react 的对应子路径引入,下面就是完整示例;样式由你的类名决定。

motion-grid.tsx
import {
  MotionGrid,
  MotionGridCells,
  type Frames,
} from '@animate-ui/react/primitives/motion-grid';

// Each frame lists the active cells as [column, row].
const frames: Frames = [
  [[1, 1]],
  [
    [0, 1],
    [1, 0],
    [1, 2],
    [2, 1],
  ],
  [
    [0, 0],
    [0, 2],
    [2, 0],
    [2, 2],
  ],
  [],
];

export function Loader() {
  return (
    <MotionGrid gridSize={[3, 3]} frames={frames} className="gap-0.5">
      <MotionGridCells className="size-1 rounded-full bg-foreground/20 data-[active=true]:bg-foreground" />
    </MotionGrid>
  );
}

动效

  • 每隔 duration 毫秒切换一帧,循环播放;帧数据就是普通的二维数组。
  • 离开视口时暂停;减少动效下停在第一帧。

所有时长都会乘以 AnimateUIProvider 的 tempo,并遵守系统的减少动效设置。

API

动效相关的 transition 与 exitTransition 是 Animate UI 唯一新增的属性;其余 props 见上表。

属性类型默认值
asChildbooleanfalse
gridSize[number, number]—
frames[number, number][][]—
durationnumber200
animatebooleantrue
…propsHTMLMotionProps<'div'>—
activePropsHTMLMotionProps<'div'>—
inactivePropsHTMLMotionProps<'div'>—
…propsHTMLMotionProps<'div'>—

未列出的属性与上游 API 完全一致,可在 官方文档 查阅。

内容对应官方文档 2026-10-18 版本。