在 React 和 Vue 项目中集成 tween.js 的最佳实践

在现代 Web 界面中，平滑的数值补间与过渡动画是构建高质感可视化大屏、Three.js 3D 交互、SVG 图表动态加载及数值滚动展示的核心能力。@tweenjs/tween.js 作为历史悠久且性能强劲的 JavaScript 补间动画库，能够根据设定的缓动方程在指定时长内平滑计算数值变化。

然而，当开发者将习惯于原生脚本环境的 tween.js 迁移到 React 或 Vue 这类现代组件化单页面框架中时，往往会直接调用全局单例 TWEEN.update() 并在回调中盲目调用框架状态更新。这种做法会导致组件作用域污染、组件卸载后帧循环（RAF）无法终止造成的内存泄漏，以及以 60fps 频率触发虚拟 DOM 递归 Diff 造成的严重掉帧。

本文将紧密围绕 React 和 Vue 两个框架的生命周期与响应式机制，详解如何以工程化的方式规范集成 tween.js，提供即拷即用的可复用封装（Custom Hook 与 Composable），并给出针对高性能场景的直接引用更新优化方案。

一、核心机制与 SPA 框架集成的关键冲突

在编写集成代码之前，必须准确理解 tween.js 的运作模式以及它与现代前端框架在运行时设计上的三大冲突点。

1. 帧驱动与全局状态污染：tween.js 本身并不内置定时器，必须由外部（通常是浏览器的 requestAnimationFrame）周期性调用 update()。默认情况下，所有补间对象都会注册到全局的 TWEEN 对象中。在多组件共存的单页面应用中，全局注册会导致不同组件的补间相互干扰，某一个组件卸载时若调用全局清空，将直接导致其余正在运行的动画骤停。
2. 组件卸载与闭包泄漏：React 与 Vue 的组件具有明确的挂载和卸载时机。如果组件销毁时没有同步取消 requestAnimationFrame 循环并停止补间，未完成的补间回调仍会持续引用已卸载组件的作用域和 DOM 节点，造成严重的内存占用，甚至抛出不可预期的运行时异常。
3. 高频更新（60fps）与虚拟 DOM Diff 的性能矛盾：在每一帧（约 16.6ms）的 onUpdate 回调中，若直接通过 setState 或触发响应式依赖重新执行组件渲染，现代框架的组件级协调（Reconciliation）与渲染树生成开销将迅速击穿帧预算，引发卡顿。

二、React 中的最佳实践：自定义 Hook 与引用隔离

在 React 项目中，最核心的原则是：绝不依赖全局单例，使用 Ref 保持实例稳定，在 useEffect 中完成闭环生命周期管理。

1. 为什么必须使用独立 Group

如果使用 import * as TWEEN from '@tweenjs/tween.js' 并调用 new TWEEN.Tween()，该补间会自动注册进全局组。当页面中有多个组件挂载不同动画时，任一组件卸载时如果调用 TWEEN.removeAll()，就会无差别杀死其他组件的动画。

正确做法是：通过 new TWEEN.Group() 为每个需要独立控制动画的组件实例创建隔离组。

2. 封装通用的 useTween 自定义 Hook

为了避免在每个组件中重复编写 requestAnimationFrame、cancelAnimationFrame、new Group() 和清除逻辑，我们可以封装一个轻量且健壮的 useTween Hook。

import { useRef, useEffect, useCallback } from 'react';
import * as TWEEN from '@tweenjs/tween.js';

export interface UseTweenOptions {
  from: Record<string, number>;
  to: Record<string, number>;
  duration?: number;
  easing?: (amount: number) => number;
  onUpdate?: (current: Record<string, number>) => void;
  onComplete?: () => void;
  autoStart?: boolean;
}

export function useTween(options: UseTweenOptions) {
  const {
    from,
    to,
    duration = 1000,
    easing = TWEEN.Easing.Quadratic.Out,
    onUpdate,
    onComplete,
    autoStart = true
  } = options;

  // 1. 创建并维护该组件独享的 tween Group 实例
  const groupRef = useRef<TWEEN.Group | null>(null);
  if (!groupRef.current) {
    groupRef.current = new TWEEN.Group();
  }

  // 2. 维护当前的 Tween 实例及 RAF 句柄
  const tweenRef = useRef<TWEEN.Tween<Record<string, number>> | null>(null);
  const rafIdRef = useRef<number | null>(null);
  const currentCoordsRef = useRef<Record<string, number>>({ ...from });

  // 动画帧主循环
  const animate = useCallback((time: number) => {
    if (groupRef.current) {
      groupRef.current.update(time);
      rafIdRef.current = requestAnimationFrame(animate);
    }
  }, []);

  const stop = useCallback(() => {
    if (rafIdRef.current !== null) {
      cancelAnimationFrame(rafIdRef.current);
      rafIdRef.current = null;
    }
    if (tweenRef.current) {
      tweenRef.current.stop();
    }
    if (groupRef.current) {
      groupRef.current.removeAll();
    }
  }, []);

  const start = useCallback(() => {
    stop(); // 启动前重置未完成状态
    currentCoordsRef.current = { ...from };

    const tween = new TWEEN.Tween(currentCoordsRef.current, groupRef.current!)
      .to(to, duration)
      .easing(easing)
      .onUpdate((obj) => {
        onUpdate?.(obj);
      })
      .onComplete(() => {
        if (rafIdRef.current !== null) {
          cancelAnimationFrame(rafIdRef.current);
          rafIdRef.current = null;
        }
        onComplete?.();
      });

    tweenRef.current = tween;
    tween.start();

    // 启动帧循环
    rafIdRef.current = requestAnimationFrame(animate);
  }, [from, to, duration, easing, onUpdate, onComplete, stop, animate]);

  useEffect(() => {
    if (autoStart) {
      start();
    }
    // 组件卸载时，必须销毁动画并释放帧句柄
    return () => {
      stop();
    };
  }, [autoStart, start, stop]);

  return { start, stop, group: groupRef.current };
}

3. React 最佳实践代码示范：平滑数字计数器

下面是一个使用 useRef 直接更新 DOM 文本节点的完整组件示例。该组件完全不需要在 60 帧动画过程中反复重新渲染，仅在补间完成后触发必要的回调。

import React, { useRef } from 'react';
import { useTween } from './useTween';
import * as TWEEN from '@tweenjs/tween.js';

export const CounterCard: React.FC<{ targetNumber: number }> = ({ targetNumber }) => {
  const textRef = useRef<HTMLSpanElement>(null);

  useTween({
    from: { value: 0 },
    to: { value: targetNumber },
    duration: 1500,
    easing: TWEEN.Easing.Cubic.Out,
    onUpdate: (coords) => {
      // 关键：直接修改 DOM 节点的 textContent，不触发 React 重渲染
      if (textRef.current) {
        textRef.current.textContent = Math.round(coords.value).toLocaleString();
      }
    },
    onComplete: () => {
      console.log('数字递增补间动画执行完毕');
    }
  });

  return (
    <div style={{ padding: 20, border: '1px solid #e2e8f0', borderRadius: 8 }}>
      <h4 style={{ margin: 0, color: '#64748b' }}>核心业务指标</h4>
      <div style={{ fontSize: 32, fontWeight: 'bold', color: '#456581' }}>
        <span ref={textRef}>0</span>
      </div>
    </div>
  );
};

三、Vue 3 中的最佳实践：组合式 API 与浅层响应式

在 Vue 3 项目中，得益于组合式 API（Composition API），状态与生命周期钩子（onMounted、onUnmounted）具有极强的内聚性。但在集成 tween.js 时，必须重点关注 Vue 3 的深层响应式追踪机制对计算性能的影响。

1. 为什么补间目标应避免使用深层 reactive

如果直接将 Vue 3 的 reactive({ x: 0 }) 作为 tween.js 的起点对象：new TWEEN.Tween(state)，由于 tween.js 在每一帧都会直接对该对象执行属性赋值操作，这将导致 Vue 的 Proxy 拦截器以 60 次/秒的频率触发 trigger() 并收集依赖。如果模板中直接绑定了该响应式变量，同样会导致模板渲染函数每秒调用 60 次。

因此在 Vue 3 中，推荐做法是：对纯动画补间过程使用普通 JavaScript 原生对象，仅在必要处采用 shallowRef 承接结果，或直接通过 ref 获取 DOM 进行属性赋值。

2. 封装 Vue 3 组合式 API：useTween.ts

在 Vue 3 中封装 useTween，可以利用组件天然的上下文自动挂载清理钩子，使消费组件的业务逻辑非常清爽。

import { onMounted, onUnmounted, ref } from 'vue';
import * as TWEEN from '@tweenjs/tween.js';

export interface UseVueTweenOptions {
  from: Record<string, number>;
  to: Record<string, number>;
  duration?: number;
  easing?: (amount: number) => number;
  onUpdate?: (current: Record<string, number>) => void;
  onComplete?: () => void;
  autoStart?: boolean;
}

export function useVueTween(options: UseVueTweenOptions) {
  const {
    from,
    to,
    duration = 1000,
    easing = TWEEN.Easing.Cubic.Out,
    onUpdate,
    onComplete,
    autoStart = true
  } = options;

  // 1. 独立作用域分组
  const group = new TWEEN.Group();
  let rafId: number | null = null;
  let currentTween: TWEEN.Tween<Record<string, number>> | null = null;

  // 使用普通对象作为内部补间实体，避免 Vue Proxy 深度拦截
  const coords = { ...from };
  const isPlaying = ref(false);

  const animate = (time: number) => {
    group.update(time);
    if (isPlaying.value) {
      rafId = requestAnimationFrame(animate);
    }
  };

  const stop = () => {
    isPlaying.value = false;
    if (rafId !== null) {
      cancelAnimationFrame(rafId);
      rafId = null;
    }
    if (currentTween) {
      currentTween.stop();
    }
    group.removeAll();
  };

  const start = () => {
    stop();
    Object.assign(coords, from);

    currentTween = new TWEEN.Tween(coords, group)
      .to(to, duration)
      .easing(easing)
      .onUpdate((obj) => {
        onUpdate?.(obj);
      })
      .onComplete(() => {
        isPlaying.value = false;
        if (rafId !== null) {
          cancelAnimationFrame(rafId);
          rafId = null;
        }
        onComplete?.();
      });

    isPlaying.value = true;
    currentTween.start();
    rafId = requestAnimationFrame(animate);
  };

  onMounted(() => {
    if (autoStart) {
      start();
    }
  });

  // 组件卸载时自动安全退出
  onUnmounted(() => {
    stop();
  });

  return {
    start,
    stop,
    isPlaying,
    group
  };
}

3. Vue 3 业务组件中的调用示例

在 <script setup> 中，我们可以直接通过 template ref 绑定 DOM 或 SVG 属性进行赋值：

<script setup lang="ts">
import { ref } from 'vue';
import { useVueTween } from './useVueTween';
import * as TWEEN from '@tweenjs/tween.js';

// 获取 SVG 进度条环的 DOM 引用
const circleRef = ref<SVGCircleElement | null>(null);
const percentageText = ref('0%');

// 周长为 2 * π * 40 ≈ 251.2
const TOTAL_DASH = 251.2;

useVueTween({
  from: { progress: 0 },
  to: { progress: 85 }, // 目标 85%
  duration: 1200,
  easing: TWEEN.Easing.Exponential.Out,
  onUpdate: (coords) => {
    const val = coords.progress;
    percentageText.value = `${Math.round(val)}%`;
    if (circleRef.value) {
      // 动态修改 SVG strokeDashoffset 属性，达到平滑进度条效果
      const offset = TOTAL_DASH * (1 - val / 100);
      circleRef.value.style.strokeDashoffset = String(offset);
    }
  }
});
</script>

<template>
  <div class="progress-box">
    <svg width="100" height="100" viewBox="0 0 100 100">
      <circle cx="50" cy="50" r="40" fill="none" stroke="#e2e8f0" stroke-width="8" />
      <circle
        ref="circleRef"
        cx="50"
        cy="50"
        r="40"
        fill="none"
        stroke="#438a80"
        stroke-width="8"
        stroke-dasharray="251.2"
        stroke-dashoffset="251.2"
        stroke-linecap="round"
        transform="rotate(-90 50 50)"
      />
      <text x="50" y="56" text-anchor="middle" font-size="16" font-weight="bold" fill="#2c3e50">
        {{ percentageText }}
      </text>
    </svg>
  </div>
</template>

四、避坑指南与跨框架落地检查清单

在实际项目落地中，除了上述基础封装外，还有几个在生产环境中频繁出现的边界缺陷与优化要点需要特别关注：

1. 标签页休眠与唤醒（Page Visibility API）的时间跳跃

现代浏览器在标签页切换到后台（如用户最小化窗口或切换 Tab）时，会显著降低甚至完全暂停 requestAnimationFrame 的执行。由于 tween.js 在执行 group.update(time) 时依赖高精度时间戳，当用户在几分钟后切回页面时，计算得出的时间差巨大，会导致动画瞬时跳变或缓动方程计算出现异常。

2. 避免对同一对象重复启动未完结的补间

当用户的交互频率高于动画时长时（例如快速多次点击按钮），如果在上一次补间尚未完成时直接对同一对象调用 .start()，tween.js 会并行记录多个补间指令，引起内部属性覆盖与抖动。必须在启动新动画之前，先调用 tween.stop() 或在 start 内部执行旧补间的取消与释放。

五、结语

在 React 和 Vue 项目中，集成 tween.js 的本质并不是简单的 API 调用，而是在外部主动驱动的动画时钟与框架被动驱动的声明式渲染管线之间建立清晰的边界。

通过使用独立的 Group 避免全局污染、在生命周期钩子中严格绑定 requestAnimationFrame 启停与清理，并借助直接引用更新绕过不必要的虚拟 DOM Diff，我们不仅能发挥出 tween.js 纯粹、敏捷的补间计算能力，更能确保大型前端应用在持续高帧率运行下的稳定性与内存安全。