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;               // 數值的十進位精確度