animate.js 核心 API 详解：play、pause 与时间轴控制

一、动画实例的初始化与控制器获取

在开始调用播放或暂停之前，必须明确动画实例在内存中的形态。以标准的现代 JavaScript 补间动画库（如 Anime.js 或自研基于该规范的轻量 animate.js）为例，每次执行动画声明时，引擎都会返回一个控制句柄（Animation Instance）。默认情况下，动画在声明后会立即开始执行；但若要将其纳入受控体系，首先需要关闭自动播放配置。

如下所示为创建受控动画实例的标准方式：

// 声明并捕获动画控制器句柄
const myAnimation = anime({
  targets: '.interactive-box',
  translateX: 320,
  rotate: '1turn',
  backgroundColor: '#659B9B',
  duration: 1200,
  easing: 'easeInOutQuad',
  autoplay: false // 关键：禁用创建即播放，转由程序逻辑主动控制
});

将 autoplay 设为 false 后，引擎已在内部完成了目标节点解析、起始属性捕获、贝塞尔曲线参数计算以及时序规划，但此时并未向浏览器注册帧调度循环。这使得动画实例处于纯净的挂起（IDLE / PAUSED）状态，等待外部指令唤醒。

二、核心播放控制：play 与 pause 的底层时钟机制

对于初学者而言，容易将 play() 与 pause() 简单等同于定时器的开启与清除。但在工业级动画引擎中，其底层设计有着严格的高精度时基对齐逻辑。

1. play() 的工作原理

调用 myAnimation.play() 时，引擎并不会从绝对时间 0 开始硬性计时，而是执行以下两步关键计算：

• 对齐起始时戳：通过 performance.now() 获取当前高精度毫秒数，并减去已播放的内部时间（startTime = performance.now() - currentTime）。这样无论是首次启动还是暂停后继续播放，时间轴都不会产生断层跳跃。
• 注册调度循环：将该动画实例推入全局调度队列，并唤醒 requestAnimationFrame 循环。在后续的每一帧（通常约 16.6ms）中，引擎依据当前系统时戳计算出线性进度 progress = (now - startTime) / duration，经过缓动函数（Easing Function）映射后，把最终计算值批量更新至 DOM 元素的内联样式中。

2. pause() 的工作原理

当执行 myAnimation.pause() 时，核心目标是“冻结”当前状态并释放计算资源：

• 持久化流逝时间：引擎读取当前瞬间的高精度时戳，将其实时流逝值固化至 currentTime 属性中，锁定当前的缓动进度。
• 注销帧调度：将当前实例从活跃动画队列中剔除。如果全局队列已无其他待运行动画，引擎会主动调用 cancelAnimationFrame 终止帧循环，杜绝无意义的 CPU 轮询开销。

3. restart() 与 reverse() 的协同扩展

除 play 与 pause 外，还有两个高度相关的方法构成了完整的状态流转闭环：

• restart()：强行将内部的 currentTime 重置为 0，同时重置已触发的回调状态，随后自动执行 play()，使动画从初始第一帧完整重播。
• reverse()：反转动画的时间轴流向（将内部 reversed 标志取反）。需要注意的是，reverse() 仅改变方向向量；如果此时动画处于暂停状态，必须紧接着调用一次 play() 才能开始沿反方向回放。

以下是具备播放、暂停、反转和重置功能的完整交互示例代码：

// 获取界面控制按钮
const btnPlay = document.querySelector('#btn-play');
const btnPause = document.querySelector('#btn-pause');
const btnReverse = document.querySelector('#btn-reverse');
const btnRestart = document.querySelector('#btn-restart');

// 绑定交互控制
btnPlay.addEventListener('click', () => {
  myAnimation.play();
});

btnPause.addEventListener('click', () => {
  myAnimation.pause();
});

btnReverse.addEventListener('click', () => {
  myAnimation.reverse();
  myAnimation.play(); // 反转后若处于暂停态，需唤醒播放
});

btnRestart.addEventListener('click', () => {
  myAnimation.restart();
});

三、精确跳转与外部驱动：seek() 的运作逻辑

在视频播放器进度条、页面滚动视差（Scroll-driven Animation）或拖拽滑块联动等场景中，动画的播放进度需要跟随外部用户的物理输入实时变化，而不是随自然时钟线性流逝。这正是 seek() 方法的核心使命。

1. seek(value) 的计算机制

seek() 接收一个目标时间（以毫秒为单位，例如 seek(600)）或在部分实现中支持归一化进度百分比。调用时，引擎会执行纯同步的数学求值：

1. 对传入值进行边界限制，确保其在 [0, duration] 区间内；
2. 根据目标时间计算当前的缓动值，并将样式立即刷入 DOM；
3. 更新实例内部的 currentTime 与 progress 属性。

最关键的是：seek() 本身不会开启 requestAnimationFrame 调度循环。如果动画在调用前是暂停的，调用后仍然保持暂停，画面将精确凝固在目标时间点的单帧视觉上。

2. 进度条联动代码示例

// 配合原生 input range 实现无级拖拽洗发带（Scrubber）
const rangeSlider = document.querySelector('#animation-scrubber');

// 初始化滑块最大值为动画总时长
rangeSlider.max = myAnimation.duration;

// 监听拖拽输入
rangeSlider.addEventListener('input', (e) => {
  const targetTime = Number(e.target.value);
  
  // 先暂停自然播放，避免内置时钟与用户拖拽产生位移冲突
  myAnimation.pause();
  
  // 瞬时跳转到指定时刻
  myAnimation.seek(targetTime);
});

四、多动画协同编排：时间轴（Timeline）控制

当页面需要同时呈现多个元素的联动时（例如卡片展开时：背景先放大、标题淡入、内容列表错落滑动、关闭按钮浮现），如果只依靠单个动画的 delay 配置或原生 onComplete 回调嵌套，开发维护将面临灾难性难题：

• 回调地狱（Callback Hell）：多层嵌套使代码高度耦合，无法统一暂停或反向回退；
• 时序脆弱：一旦调整中间某个步骤的 duration，后续所有步骤的 delay 都必须手动人工重新计算；
• 时钟漂移：多个独立的动画实例各自维护独立的 rAF 循环，当浏览器掉帧或页面卡顿时，各动画进度极易失去同步。

1. 时间轴的本质与架构

时间轴（Timeline）本质上是一个复合动画容器。它自身也是一个遵循标准控制器接口的动画实例（同样拥有 play()、pause()、reverse()、seek()），但它的职责不是直接作用于某个 DOM，而是统一调度容纳在其内部的所有子动画（Tracks）。

向时间轴添加子动画时，调用 timeline.add(targetOptions, offset)。其中第二个参数 offset（时间偏移量 / 插入位置）是控制整个多轨道节奏的精髓。

2. 时间偏移参数（Offset）的四种规则详解

通过合理配置 offset 参数，可以实现各种复杂的时间拓扑关系：

以下代码直观展示了这四种偏移语法的组合使用：

// 创建全局主时间轴
const masterTimeline = anime.timeline({
  autoplay: false,
  easing: 'easeOutCubic'
});

masterTimeline
  // 1. 轨道 A：默认从 0ms 开始，耗时 600ms
  .add({
    targets: '.panel-bg',
    scaleY: [0, 1],
    duration: 600
  })
  // 2. 轨道 B：固定在时间轴 400ms 处启动，耗时 500ms
  .add({
    targets: '.panel-title',
    translateY: [-20, 0],
    opacity: [0, 1],
    duration: 500
  }, 400)
  // 3. 轨道 C：在前一个动画（轨道 B）结束前提前 200ms 启动
  .add({
    targets: '.panel-body',
    translateY: [30, 0],
    opacity: [0, 1],
    duration: 600
  }, '-=200')
  // 4. 轨道 D：与轨道 C 同一时刻启动，并行执行
  .add({
    targets: '.panel-footer-btn',
    scale: [0.8, 1],
    opacity: [0, 1],
    duration: 400
  }, '<');

五、实践演练：基于时间轴构建模态展开与回退交互

理解了核心 API 后，我们通过一个完整的实际工程案例来串联所有知识点：实现一个点击触发卡片展开，再次点击平滑原路收起的交互组件。

步骤一：定义 HTML 结构与初态 CSS

<div class="card-widget">
  <button id="toggle-trigger" class="trigger-btn">展开详情</button>
  <div class="card-overlay" style="transform: scale(0.95); opacity: 0; pointer-events: none;">
    <h3 class="card-header" style="transform: translateY(-15px); opacity: 0;">核心监控指标</h3>
    <div class="card-content" style="opacity: 0;">
      <p>系统已稳定运行 128 天，无任何未捕获异常。</p>
    </div>
  </div>
</div>

步骤二：声明时间轴并注入补间轨道

// 初始化时间轴实例
const cardTl = anime.timeline({
  autoplay: false,
  easing: 'easeInOutQuad'
});

// 注入各轨道动画
cardTl
  .add({
    targets: '.card-overlay',
    scale: [0.95, 1],
    opacity: [0, 1],
    duration: 350,
    begin: () => {
      document.querySelector('.card-overlay').style.pointerEvents = 'auto';
    }
  })
  .add({
    targets: '.card-header',
    translateY: [-15, 0],
    opacity: [0, 1],
    duration: 300
  }, '-=150')
  .add({
    targets: '.card-content',
    opacity: [0, 1],
    duration: 300
  }, '-=150');

步骤三：控制器事件监听与双向驱动

利用时间轴的 play() 和 reverse()，无需维护两套正向和反向的 CSS 类名或单独编写收起逻辑，仅仅通过翻转时间轴流向即可实现完美的双向过渡：

let isExpanded = false;
const toggleBtn = document.querySelector('#toggle-trigger');

toggleBtn.addEventListener('click', () => {
  if (!isExpanded) {
    // 展开：确保正向播放
    if (cardTl.reversed) cardTl.reverse();
    cardTl.play();
    toggleBtn.textContent = '收起详情';
    isExpanded = true;
  } else {
    // 收起：反转并播放回退动画
    if (!cardTl.reversed) cardTl.reverse();
    cardTl.play();
    toggleBtn.textContent = '展开详情';
    isExpanded = false;
  }
});

六、核心 API 总结与工程避坑指南

为了在实际团队开发中规范使用动画控制器，避免常见性能和逻辑陷阱，图 4 给出了各核心 API 的特性对比与工程决策依据：

关键避坑原则与性能优化建议：

1. 切忌在事件回调中频繁 new 动画实例：
   许多开发者习惯在按钮点击事件内直接书写 anime({...})。如果用户连续快速点击，上一个动画尚未完成，新动画又重新创建，会导致多个 rAF 实例争抢同一 DOM 属性，引发严重的界面抖动与内存泄漏。正确做法是：页面初始化时声明单一实例或 Timeline，事件触发时仅调用其 play()、pause() 或 restart()。
2. 单页应用（SPA）必须在销毁生命周期中执行清理：
   在 React、Vue 等现代框架中，如果组件已从 DOM 树卸载，但动画实例仍处于 PLAYING 状态，其内部的 requestAnimationFrame 会持续尝试访问已脱离文档流的 DOM 节点，造成隐蔽的内存泄漏和报错。务必在 useEffect 的清理函数或 onBeforeUnmount 钩子中显式调用 instance.pause() 并解除实例引用。
3. 严格限定补间属性为合成层（Compositor-only）属性：
   在时间轴中编排动画时，优先使用 transform（translateX、translateY、scale、rotate）和 opacity。避免使用 width、height、top、left 等触发布局重排（Reflow）的属性。这不仅能够保证 60fps/120fps 的丝滑帧率，也能避免大量子动画并行时主线程卡死导致的丢帧现象。