# Anime.js v4

> 分类：`libs/animation/` · 档位：**评估** · 更新时间：2026-11-17

## 1. 基本信息

| 项 | 内容 |
|---|---|
| 当前版本 | 4.5.0（官网同时维护 3.2.2 / 2.1.0 旧线） |
| License | MIT |
| 维护方 | Julian Garnier |
| 仓库 / 文档 | https://github.com/juliangarnier/anime · https://animejs.com |
| 最近 release | 4.5.0（官网首页标注） |

## 2. 一句话定位

做"时间轴 + 补间 + SVG + 滚动观察"的轻量动画引擎；v4 重写为模块化 ESM。
它**不提供** scroll pin（钉住）能力，也不负责布局级的滚动编排。

## 3. 体积

官网给出的模块体积（min，未压缩）：

| 模块 | min |
|---|---|
| Timer（基础） | 5.60 KB |
| Animation | 5.20 KB |
| Timeline | 0.55 KB |
| Scroll | 4.30 KB |
| SVG | 0.35 KB |
| Stagger | 0.48 KB |
| Spring | 0.52 KB |
| Scope | 0.22 KB |
| Animatable | 0.40 KB |
| WAAPI | 3.50 KB |
| Draggable | 6.41 KB |
| **全量** | **27.13 KB** |

不含 Draggable / WAAPI 的常见组合约 17–18 KB min，gzip 估算 7 KB 量级（**估算，待实测**）。

## 4. 核心 API

```js
import { animate, createTimeline, stagger, onScroll, createScope } from 'animejs';

// 补间
animate('.card', { y: [40, 0], opacity: [0, 1], ease: 'outExpo', duration: 700 });

// 滚动同步（类似 scrub）
animate('.bar', { scaleX: 1, autoplay: onScroll({ sync: true }) });

// 编排
createTimeline().add('.dot', { scale: [0, 1] }, stagger(40));

// 作用域：选择器自动限定在 root 内
createScope({ root: document.querySelector('#lss-root') }).add(() => {
  animate('.card', { opacity: [0, 1] });
});
```

## 5. 适用 / 不适用

- **适用**：入场与时间轴动画、SVG 描线 / 变形 / 运动路径、需要按需 tree-shaking 的项目、需要内置作用域隔离的嵌入式区块。
- **不适用**：依赖 scroll pin 的横向滚动叙事、需要复杂 ScrollTrigger 编排（batch / snap / 多层 pin）的场景。

## 6. 硬缺口与已知坑

- **没有 pin**：必须用 CSS `position: sticky` 自行实现"钉住"，再按滚动进度驱动 `translateX`。
- 没有 ScrollTrigger 的 `invalidateOnRefresh` 等价物，resize 后需手动重算。
- v4 与 v3 API 不兼容，旧教程代码不能直接迁移。
- 客户端重渲染（SPA / 动态插入区块）时需要显式 `revert()` / `scope.revert()`，否则会残留动画实例。

## 7. 受限环境可用性

| 环境 | 结论 | 说明 |
|---|---|---|
| 无构建（`<script type="module">`） | 可用 | 需用 ESM 构建产物，按路径 import |
| ESM / 打包器 | 可用 | 官方主推方式，可 tree-shake |
| SSR | 需守卫 | 只在浏览器端初始化 |
| 客户端重渲染 | 需处理生命周期 | 重渲染时 `revert()`，作用域用 `createScope({ root })` |

## 8. 稳定性评分

| 维度 | 评分 | 依据 |
|---|---|---|
| 维护活跃度 | 5 | v4 重写后持续迭代，官网更新到 4.5.0 |
| 版本与破坏性变更 | 3 | v3 → v4 为大版本不兼容 |
| 采用度 | 4 | 长期主流动效库，社区案例多 |
| 体积与按需 | 5 | 模块化，全量 27 KB min |
| 生态兼容 | 4 | 纯 JS/ESM，无框架绑定 |
| License | 5 | MIT |

## 9. 替代品对比

| 库 | 优势 | 劣势 | 何时选它 |
|---|---|---|---|
| GSAP + ScrollTrigger | pin / batch / snap 等滚动编排最全 | 体积大 | 需要钉住式滚动叙事时 |
| Motion One | 基于 WAAPI，体积小，Web Animations 语义 | 滚动能力弱于 ScrollTrigger | 只做轻量交互动画 |
| 原生 WAAPI + CSS | 零依赖 | 编排与 SVG 能力弱 | 简单状态过渡 |
