Anime.js v4：2026 年 JavaScript 动画引擎完全指南

# 安装最新版本（截至 2026 年 5 月为 v4.3.6）
npm install animejs@latest

# 或安装指定版本
npm install animejs@4.3.6

// 核心——永远可用
import { animate, stagger, createSpring, createTimer } from 'animejs';
import { waapi } from 'animejs';
import { engine, defaults } from 'animejs';
import { utils } from 'animejs';

// 子路径导入（v4.2+）
import { createTimeline } from 'animejs/timeline';
import { createScope } from 'animejs/scope';
import { createDraggable } from 'animejs/draggable';
import { splitText } from 'animejs/text';
import { createMotionPath, createDrawable } from 'animejs/svg';
import { eases, spring } from 'animejs/easings';

<script type="module">
  import { animate, stagger } from 'https://esm.sh/animejs@4.3.6';

  animate('.box', {
    x: { to: 300 },
    duration: 1000,
    ease: 'outQuint',
  });
</script>

animate('.element', {
  // 动画属性
  x: { to: 300 },           // 单一属性含 from/to
  rotate: { from: 0, to: 360 }, // 明确指定 from 与 to
  scale: 2,                 // 简写（等同于 to: 2）
  backgroundColor: '#ff0',  // CSS 颜色（支持含透明度的十六进制：#ff0a）

  // 时间设置
  duration: 1000,           // 毫秒（默认值因情况而异）
  delay: 200,               // 开始前的延迟
  ease: 'outQuint',         // 缓动函数（参见下方缓动表）
  loop: 2,                  // 额外重复次数（0 = 不循环）
  alternate: true,          // 每次循环时反向
  reversed: false,          // 从结束值开始
  loopDelay: 0,             // 循环之间的暂停（取代 v3 的 endDelay）

  // 渲染
  composition: 'replace',   // 'replace' | 'blend' | 'none'
  modifier: utils.round(2), // 数值后处理
  frameRate: 60,            // 限制 FPS
  playbackRate: 1,          // 速度倍率

  // 回调
  onBegin: () => {},        // 动画（含延迟）开始时
  onBeforeUpdate: () => {}, // 每次更新 tick 之前
  onUpdate: (anim) => {},   // 每一帧
  onRender: (anim) => {},   // 数值实际变更时
  onLoop: (anim) => {},     // 每次循环结束时
  onPause: (anim) => {},    // 暂停时
  onComplete: (anim) => {}, // 完全结束时
});

// 1. 数组式（最灵活——每个元素是一个关键帧）
animate('.box', [
  { rotate: { to: 90 }, duration: 500 },
  { rotate: { to: 180 }, duration: 500 },
  { rotate: { to: 360 }, duration: 500 },
]);

// 2. 持续时间式（进度根据持续时间计算）
animate('.box', {
  rotate: {
    0: 0,    // 0ms——开始
    500: 90, // 500ms——关键帧 1
    1000: 180, // 1000ms——关键帧 2
    2000: 360, // 2000ms——关键帧 3
  }
});

// 3. 百分比式（进度相对于总持续时间）
animate('.box', {
  rotate: {
    '0%': 0,
    '25%': 90,
    '50%': 180,
    '100%': 360,
  }
});

// 4. 偏移式（明确偏移量以精确控制时间）
animate('.box', {
  rotate: { to: 360 },
  offset: [0, 500, 1000, 2000],
  value: [0, 90, 180, 360],
});

// Blend 示例——两个重叠的颜色动画平滑融合
animate('.box', {
  backgroundColor: { to: '#f00' },
  duration: 1000,
});

animate('.box', {
  backgroundColor: { to: '#00f' },
  duration: 1000,
  delay: 500,
  composition: 'blend', // 通过紫色从红色插值到蓝色
});

import { animate, createSpring } from 'animejs';

const spring = createSpring({
  mass: 1,        // 越大 = 振荡越慢
  stiffness: 200, // 越高 = 越干脆
  damping: 10,    // 越高 = 弹跳越少
  velocity: 0,    // 初始速度
  bounce: 0.5,    //（v4.2+）控制弹簧弹跳强度，0-1
});

animate('.ball', {
  translateY: { to: 300 },
  ease: spring,
  loop: true,
  alternate: true,
});

import { createTimeline } from 'animejs/timeline';

const tl = createTimeline({
  defaults: { ease: 'outQuad', duration: 300 },
  loop: 1,
});

// 使用位置标签加入动画
tl.add('.box-a', { x: { to: 200 } })            // 立即开始
  .add('.box-b', { scale: { to: 1.5 } }, '+=200')  // 前一个结束后 200ms
  .add('.box-c', { rotate: { to: 180 } }, '<<')     // 前一个动画的起点
  .label('midpoint')                                 // 命名标记
  .add('.box-d', { y: { to: 100 } }, 'midpoint')    // 在标签位置
  .add('.box-e', { opacity: { to: 0 } }, 'midpoint+=500') // 标签后 500ms
  .play();

import { animate } from 'animejs';
import { createMotionPath } from 'animejs/svg';

const { translateX, translateY, rotate } = createMotionPath('#path');

animate('.car', {
  translateX,
  translateY,
  rotate,
  duration: 3000,
  ease: 'outQuint',
});

import { createDrawable } from 'animejs/svg';

const drawable = createDrawable('#my-path'); // 或 createDrawable('path')

animate(drawable, {
  draw: '0 1', // 从绘制 0% 到 100%
  duration: 2000,
  ease: 'outQuad',
});

// 将一个路径变形成另一个
animate('#shape', {
  d: { to: '#target-shape' }, // 变形路径数据
  duration: 1500,
  ease: 'inOutQuint',
});

import { splitText } from 'animejs/text';

const split = splitText({
  text: 'Anime.js v4 makes text dance!',
  by: 'word',      // 'char' | 'word' | 'line' | 'all'
  tag: 'span',     // 用于包裹每个片段的 HTML 元素
});

import { animate, stagger } from 'animejs';

animate(split.nodes, {
  translateY: { from: -20, to: 0 },
  opacity: { from: 0, to: 1 },
  duration: 600,
  delay: stagger(50), // 每个单词／字符交错出现
  ease: 'outQuad',
});

import { createDraggable, createSpring } from 'animejs';

const drag = createDraggable({
  el: '.card',
  container: '.stack',
  bounds: { x: [0, 400], y: [0, 400] },
  releaseEase: createSpring({ stiffness: 150, damping: 15 }),
  dragThreshold: 10,   //（v4.2.1+）开始拖拽前的最小像素数
  onStart: () => {},
  onDrag: () => {},
  onDrop: () => {},
  onSnap: () => {},
});

// 后续使用
drag.destroy();

import { createScope } from 'animejs/scope';

// 在 Svelte onMount / React useEffect 内部
const scope = createScope({ root: containerElement });

// 限域查询选择器
scope.qs('.card');    // 仅在根元素范围内
scope.qsa('.item');   // 根元素内所有符合的元素

// 注册自定义方法
scope.registerMethod('customAnimation', (el) => {
  animate(el, { scale: 1.2 });
});

// 卸载时清理
onDestroy(() => scope.revert());

import { waapi, stagger } from 'animejs';

waapi.animate('span', {
  translate: '0 -2rem',
  delay: stagger(100),
  duration: 600,
  loop: true,
  alternate: true,
  ease: 'inOut(2)',
});

import { engine } from 'animejs';

engine.defaults = { duration: 500, ease: 'outQuad' }; // 全局默认
engine.useDefaultMainLoop = false;  // 禁用内置循环
engine.update();                     // 手动更新帧
engine.pauseOnDocumentHidden = true; // 标签页隐藏时暂停
engine.timeUnit = 'ms';             // 'ms' 或 's'
engine.precision = 2;               // 数值的十进制精确度