# @aura-react-comp/motion 中文文档

规范地址：https://npmcn.com/package/%40aura-react-comp/motion/

版本：0\.2\.11
npm 元数据更新时间：2026-11-02T07:26:03.354Z
中文译文更新时间：2026-11-07T04:56:27.034Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aura-react-comp/motion
原文对照：https://npmcn.com/package/%40aura-react-comp/motion/?lang=original
项目主页：https://asbeforelandy.github.io/aura/motion-components
源码仓库：https://github.com/AsBeforeLandy/aura

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：137 kB，109 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0，lottie-web \>=4\.0\.0
- 首次发布：2026-10-13T23:22:23.476Z
- 最新版本发布：2026-11-02T07:26:02.943Z
- 近 30 天下载量：2620（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

Aura 动效组件库 — 令牌驱动的场景化动画组件（进出场、数字与文字特效、滚动驱动、编排、手势）

## 安装

```sh
npm install @aura-react-comp/motion
```

也可以使用：`pnpm add @aura-react-comp/motion`、`yarn add @aura-react-comp/motion`、`bun add @aura-react-comp/motion`

## README

# @aura-react-comp/motion

Aura 动效组件库 —— 令牌驱动的场景化动画组件。

## 安装

```bash
npm i @aura-react-comp/motion
```

`react` / `react-dom` 为 peer 依赖；`lottie-web` 为**可选** peer（仅 `<LottiePlayer>` 需要）。

## 引入令牌

所有组件的时长与缓动都走动效令牌，请一次性引入（或经 ui 联动包级联引入）：

```tsx
import '@aura-react-comp/motion/tokens.css';
```

## 快速开始

```tsx
import { Slide, NumberTicker, Reveal } from '@aura-react-comp/motion';

// 进出场（保留式：DOM 常驻）
<Slide visible={open} direction="up" distance="md">…</Slide>

// 进出场（卸载式：配合 AnimatePresence）
<AnimatePresence>{open && <Zoom key="modal">…</Zoom>}</AnimatePresence>

// 数字滚动
<NumberTicker value={128940} />

// 进入视口揭示
<Reveal index={0}>…</Reveal>
```

## 组件清单（30 个）

**基础（primitive）**

| 组件 | 场景 |
| --- | --- |
| Slide / Fade / Zoom / Collapse | 进出场四件套（`Collapse` 用 `open`，其余用 `visible`） |
| Reveal | 视口揭示，`variant`: fade / blur / mask / scale |
| NumberTicker | 数字滚动（逐位独立弹簧、位间错峰、tabular-nums） |
| SplitText | 文字拆分进场，`variant`: fade / rise / flip |
| Typewriter | 打字机（AI 流式回复补位） |
| InViewport | 进入视口通用包装 |
| Magnetic | 磁吸悬停 |
| SkeletonShimmer | 骨架屏光泽（`index` 错峰出光） |
| FocusRing | 键盘焦点环跟随 |
| Keyframes | 令牌驱动关键帧（白名单：opacity / scale / x / y / rotate / skew） |
| TextShimmer | 文字流光（AI 生成中） |
| TypingDots | 思考三点脉冲（`role="status"`） |
| GradientBorder | 流光渐变边框（旋转 conic 光带） |
| Marquee | 无缝滚动横幅 |

**复杂场景（composed）**

| 组件 | 场景 |
| --- | --- |
| PageTransition | 路由转场（快退慢进） |
| ViewTransition | 原生 View Transitions 渐进增强 |
| ScrollDriven / ScrollProgressBar | 滚动进度驱动 |
| Parallax | 多层视差 |
| PathDraw | SVG 路径描边 |
| Timeline / TimelineStep / useSequence | 时间线编排 |
| FlipList | 列表增删自动重排（FLIP） |
| Draggable | 自由拖拽（约束 / 网格吸附 / 惯性） |
| Reorder / ReorderGroup / ReorderItem | 拖拽排序 |
| LayoutGroup | 共享元素过渡 |
| Cursor | 自定义光标跟随 |
| Confetti | 庆祝粒子（纸条物理 + 翻面） |
| Aurora | 渐变氛围背景 |
| LottiePlayer | Lottie 动画（可选 peer） |
| TiltCard | 3D 倾斜卡片（指针驱动 + 光泽跟随） |
| ScrollScaleCard | 滚动缩放揭示（landing 卡片） |

编排 API：`AnimatePresence`、`motion`（源语）、`MotionConfig`、`useReducedMotion`、 `useInView`、`useAnimationControls`。

## 与 AI 对话场景组合

```tsx
import { Bubble } from '@aura-react-comp/x';
import { TypingDots, TextShimmer, GradientBorder } from '@aura-react-comp/motion';

// 思考中（Bubble 的 content 是字符串，自定义节点走 contentRender）
<Bubble role="assistant" content="" contentRender={() => <TypingDots />} />

// 生成中流光标题（header 接受 ReactNode）
<Bubble role="assistant" header={<TextShimmer>正在生成…</TextShimmer>} content="…" />

// 流光边框回答卡片
<GradientBorder><Bubble role="assistant" content="…" /></GradientBorder>
```

motion 是 x 的**可选增强**——未安装不影响 x 的任何功能。完整场景见文档站 [动效场景配方](https://asbeforelandy.github.io/aura/guide/motion-recipes)。

## 设计约定

1.  **只从本包导入**，不要直接依赖 `motion/react`（引擎隔离层）；
2.  时长 / 缓动 / 位移传**令牌档位名**（`'fast'`、`'decelerate'`、`'md'`），不传裸数值；
3.  组件只动画 `transform` / `opacity`（`Collapse` 的 height 为既有例外，勿用于长列表）。

## 可访问性（三层降级）

| 层 | 机制 |
| --- | --- |
| 令牌层 | `prefers-reduced-motion: reduce` 时 CSS 令牌时长归零 |
| 引擎层 | `<MotionConfig reducedMotion="user">` 全局开关 |
| 组件层 | 每组件内 `useReducedMotion()` 分支（Confetti 不撒、Cursor 不跟随……） |

## 渐进增强声明

运行时依赖 Motion 引擎的浏览器基线（高于 ui 包的 chrome 80）。不满足时组件直接呈现 **终态**，无中间帧、无报错，页面功能不受影响；`<ViewTransition>` 在不支持的浏览器 自动降级为普通过渡。

## 常见问题

### @aura-react-comp/motion 是什么？

Aura 动效组件库 — 令牌驱动的场景化动画组件（进出场、数字与文字特效、滚动驱动、编排、手势）

### 如何安装 @aura-react-comp/motion？

在项目目录运行 npm install @aura-react-comp/motion，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）、react-dom（\>=18\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aura-react-comp/motion 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aura-react-comp/motion 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @aura-react-comp/motion 可以商用吗？

@aura-react-comp/motion 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @aura-react-comp/motion 的下载量有多少？

根据 npm 官方下载统计，@aura-react-comp/motion 在 2026/10/07 – 2026/11/05 这 30 天内被下载 2,620 次，日均约 87 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aura-react-comp/motion 还在维护吗？

最新版本 0\.2\.11 发布于 2026/11/02（5 天前）；至今共发布 18 个版本，其中过去 12 个月发布了 18 个；首次发布于 2026/10/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。