怎么使用 tween.js 实现链式调用与多动画序列同步

一、准备环境与 tween.js 运作基础

在构建复杂的动画序列之前，需要明确 tween.js 的驱动机制。tween.js 是一个轻量级数值插值引擎，它本身并不直接操作 DOM 样式或 Canvas，而是通过每一帧对 JavaScript 目标对象的数值进行平滑改变，再通过 onUpdate 回调把最新值交由开发者赋予具体视图。

通过 npm 安装现代包 @tweenjs/tween.js，或者在页面中直接引入脚本：

// 引入官方现代模块
import * as TWEEN from '@tweenjs/tween.js';

// 基础启动与更新驱动
function animate(time) {{
  requestAnimationFrame(animate);
  TWEEN.update(time);
}}
requestAnimationFrame(animate);

驱动循环中的 TWEEN.update(time) 是所有链式动画和同步序列能够按照真实时间推进的心脏。如果未在动画帧中持续调用此更新函数，任何补间状态都不会发生位移。

二、使用 .chain() 实现线性串行链式调用

当业务需求属于“步骤 A 完成后紧接着执行步骤 B，再执行步骤 C”这种单向先后顺序时，原生自带的 .chain() 是最简洁直接的实现手段。

1. 串行链式的调用写法

创建各个独立的补间实例后，调用 tweenA.chain(tweenB)。此时启动 tweenA，当其持续时间结束并到达目标状态时，内部调度器会自动触发 tweenB.start()。

const box = {{ x: 0, y: 0, opacity: 1 }};

// 阶段 1：向右平移 300px
const tweenMoveRight = new TWEEN.Tween(box)
  .to({{ x: 300 }}, 800)
  .easing(TWEEN.Easing.Cubic.Out);

// 阶段 2：向下平移 200px
const tweenMoveDown = new TWEEN.Tween(box)
  .to({{ y: 200 }}, 600)
  .easing(TWEEN.Easing.Quadratic.Out);

// 阶段 3：淡出消失
const tweenFadeOut = new TWEEN.Tween(box)
  .to({{ opacity: 0 }}, 400)
  .easing(TWEEN.Easing.Linear.None);

// 构建串行调用链：MoveRight -> MoveDown -> FadeOut
tweenMoveRight.chain(tweenMoveDown);
tweenMoveDown.chain(tweenFadeOut);

// 只需显式启动链表头节点
tweenMoveRight.start();

2. 多节点闭环与循环往复队列

如果需要实现物体在多个关键坐标间持续巡逻或往复巡检，除了常规的 .repeat(Infinity).yoyo(true) 之外，.chain() 还能实现具有不同缓动函数的闭环序列。只需将尾节点的链式下游重新指向头节点：

// A -> B -> C -> A 实现三点循环移动
tweenA.chain(tweenB);
tweenB.chain(tweenC);
tweenC.chain(tweenA); // 闭环接力

tweenA.start();

三、核心对比：原生链式与多动画聚合同步的关键差异

许多开发者在项目进阶时容易遇到一个瓶颈：如果一个元素在向右移动（耗时 500ms）的同时自身在变大（耗时 1000ms），随后需要等待位移与变大两者都彻底完成后，再执行第三个弹跳动画。此时单凭 .chain() 会暴露出结构性限制。

为什么这一差异至关重要？在多属性并发场景下，如果使用 tweenA.chain(tweenB, tweenC)，tweenA 完成时会同时启动 tweenB 和 tweenC。但如果我们想在两者都结束时触发 tweenD，若写成 tweenB.chain(tweenD)，因为 tweenB 只有 500ms，tweenD 会在第 500ms 强行执行，而此时 1000ms 的 tweenC 仍在半路上，UI 呈现出动作割裂或属性覆盖。通过时间差硬编码 delay 既繁琐又脆弱，一旦发生掉帧或参数调整，序列立刻产生错位。

四、多动画序列同步的工程化实现方案

要实现多轨道并发且可靠汇聚的动画序列，业界通用且稳健的方式主要有两种：基于 Promise 的状态同步栅栏，以及基于 TWEEN.Group 的分轨通道管理。

1. 方案一：Promise 栅栏模式（解决多分支汇聚）

将 tween.js 补间实例封装为一个返回 Promise 的辅助函数。当动画正常触发 onComplete 时 resolve，若外部手动调用 onStop 时也进行安全处理。这样就可以利用标准的 Promise.all() 实现分支汇聚：

/**
 * 将单个 Tween 包装为 Promise 栅栏节点
 */
function toPromise(tween) {{
  return new Promise((resolve) => {{
    tween.onComplete(() => resolve({ status: 'completed' }));
    tween.onStop(() => resolve({ status: 'stopped' }));
    tween.start();
  }});
}}

// 编写具备并发同步的编排工作流
async function playCompositeSequence() {{
  const target = {{ x: 0, scale: 1, opacity: 0 }};

  // 第一阶段：单线淡入预备
  const prepTween = new TWEEN.Tween(target)
    .to({{ opacity: 1 }}, 300)
    .easing(TWEEN.Easing.Linear.None);
  await toPromise(prepTween);

  // 第二阶段：多轨并发（位移 800ms，缩放 400ms，异构时长）
  const moveTween = new TWEEN.Tween(target)
    .to({{ x: 250 }}, 800)
    .easing(TWEEN.Easing.Cubic.Out);

  const scaleTween = new TWEEN.Tween(target)
    .to({{ scale: 1.5 }}, 400)
    .easing(TWEEN.Easing.Back.Out);

  // 等待所有并发补间彻底完成（栅栏放行点）
  await Promise.all([toPromise(moveTween), toPromise(scaleTween)]);

  // 第三阶段：所有并发就绪后，执行收尾复位
  const finishTween = new TWEEN.Tween(target)
    .to({{ scale: 1, opacity: 0.8 }}, 500)
    .easing(TWEEN.Easing.Quadratic.InOut);
  await toPromise(finishTween);
}}

2. 方案二：使用 TWEEN.Group 隔离独立动画轨道

在较大型的前端工程中，页面可能同时存在“全局背景环境粒子动效”与“用户交互弹窗动效”。如果所有动画都挂在默认的全局 TWEEN 对象下，执行 TWEEN.removeAll() 会把背景粒子也一并销毁。

通过实例化 new TWEEN.Group()，可以为特定动画序列开辟专属通道：

// 创建专属通道组
const modalGroup = new TWEEN.Group();

// 构造补间时传入 group 实例作为第二个参数
const modalTween1 = new TWEEN.Tween(modalState, modalGroup)
  .to({{ y: 0 }}, 400);

const modalTween2 = new TWEEN.Tween(modalState, modalGroup)
  .to({{ opacity: 1 }}, 300);

modalTween1.chain(modalTween2);
modalTween1.start();

// 独立渲染驱动：只更新本组，互不干扰
function renderLoop(time) {{
  requestAnimationFrame(renderLoop);
  modalGroup.update(time); // 独立推进
}}

// 关闭弹窗时仅销毁本组补间
function closeModal() {{
  modalGroup.removeAll();
}}

五、核心注意事项与避坑指南

六、总结与落地建议

掌握 tween.js 的序列编排可以遵循以下决策路径：

• 对于明确无分支的线性流转（如单向三段式转场），直接使用 tweenA.chain(tweenB).chain(tweenC)，代码简洁且运行时开销最小。
• 对于循环巡检动效，使用首尾互连的 .chain() 形成闭环，注意保持各段起终点闭合。
• 对于存在多元素并发、异构动画时长，且后续操作依赖全部到位的场景，果断采用包装后的 Promise 栅栏（Promise.all）进行收敛。
• 在多组件共存的复杂页面中，使用 new TWEEN.Group() 为每个功能模块建立独立通道，避免全局状态污染与批量销毁误伤。