gsap-frameworks

在 Vue、Svelte 和其他框架中使用 GSAP

何时使用此技能

在 Vue（或 Nuxt）、Svelte（或 SvelteKit）或其他使用生命周期（挂载/卸载）的组件框架中编写或审查 GSAP 代码时使用。对于 React，请使用 gsap-react（useGSAP hook、gsap.context()）。

相关技能： 对于补间和时间轴，请使用 gsap-core 和 gsap-timeline；对于基于滚动的动画，请使用 gsap-scrolltrigger；对于 React，请使用 gsap-react。

原则（适用于所有框架）

• 在组件的 DOM 可用后（例如 onMounted、onMount），创建补间和 ScrollTrigger。
• 在卸载（或等效阶段）时终止或还原它们，确保它们不会在已脱离 DOM 的节点上运行，也不会造成内存泄漏。
• 将选择器限制在组件根元素内，这样 .box 等选择器只会匹配该组件内的元素，而不会匹配页面其他部分的元素。

Vue 3（Composition API）

使用 onMounted 在组件进入 DOM 后运行 GSAP。使用 onUnmounted 进行清理。

import { onMounted, onUnmounted, ref } from "vue";
import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
gsap.registerPlugin(ScrollTrigger); // once per app, e.g. in main.js

export default {
  setup() {
    const container = ref(null);
    let ctx;

    onMounted(() => {
      if (!container.value) return;
      ctx = gsap.context(() => {
        gsap.to(".box", { x: 100, duration: 0.6 });
        gsap.from(".item", { autoAlpha: 0, y: 20, stagger: 0.1 });
      }, container.value);
    });

    onUnmounted(() => {
      ctx?.revert();
    });

    return { container };
  }
};

• ✅ gsap.context(scope) — 将容器 ref（例如 container.value）作为第二个参数传入，这样 .item 等选择器就会限定在该根元素内。回调中创建的所有动画和 ScrollTrigger 都会被跟踪，并在调用 ctx.revert() 时还原。
• ✅ onUnmounted — 始终调用 ctx.revert()，以终止补间和 ScrollTrigger，并还原内联样式。

Vue 3（script setup）

使用 <script setup> 和 refs，方法相同：

<script setup>
import { onMounted, onUnmounted, ref } from "vue";
import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";

const container = ref(null);
let ctx;

onMounted(() => {
  if (!container.value) return;
  ctx = gsap.context(() => {
    gsap.to(".box", { x: 100 });
    gsap.from(".item", { autoAlpha: 0, stagger: 0.1 });
  }, container.value);
});

onUnmounted(() => {
  ctx?.revert();
});
</script>

<template>
  <div ref="container">
    <div class="box">Box</div>
    <div class="item">Item</div>
  </div>
</template>

Svelte

使用 onMount 在 DOM 就绪后运行 GSAP。使用 onMount 返回的清理函数（或跟踪上下文并在响应式代码块/组件销毁时进行清理）来还原。Svelte 5 使用不同的生命周期；原则相同：在“挂载”时创建，在“销毁”时还原。

<script>
  import { onMount } from "svelte";
  import { gsap } from "gsap";
  import { ScrollTrigger } from "gsap/ScrollTrigger";

  let container;

  onMount(() => {
    if (!container) return;
    const ctx = gsap.context(() => {
      gsap.to(".box", { x: 100 });
      gsap.from(".item", { autoAlpha: 0, stagger: 0.1 });
    }, container);
    return () => ctx.revert();
  });
</script>

<div bind:this={container}>
  <div class="box">Box</div>
  <div class="item">Item</div>
</div>

• ✅ bind:this={container} — 获取根元素的引用，以便将其传给 gsap.context(scope)。
• ✅ return () => ctx.revert() — Svelte 的 onMount 可以返回清理函数；在其中调用 ctx.revert()，以便在组件销毁时执行清理。

限定选择器范围

不要使用可能匹配当前组件外部元素的全局选择器。始终将 scope（容器元素或 ref）作为第二个参数传给 gsap.context(callback, scope)，以便回调中运行的任何选择器都仅限于该子树。

• ✅ gsap.context(() => { gsap.to(".box", ...) }, containerRef) — 只会在 containerRef 内查找 .box。
• ❌ 在组件中不带上下文范围运行 gsap.to(".box", ...)，可能会影响其他实例或页面的其余部分。

清理 ScrollTrigger

当你在补间/时间轴中使用 scrollTrigger 配置或调用 ScrollTrigger.create() 时，会创建 ScrollTrigger 实例。它们会包含在 gsap.context() 中，并在调用 ctx.revert() 时还原。因此：

• 在与补间相同的 gsap.context() 回调中创建 ScrollTrigger。
• 影响触发位置的布局发生变化时（例如数据加载后），调用 ScrollTrigger.refresh()；在 Vue/Svelte 中，这通常意味着要等到 DOM 更新后（例如 Vue 中的 nextTick、Svelte 中的 tick，或异步内容加载完成后）。

何时创建与终止

生命周期	操作
Mounted	在 gsap.context(scope) 内创建补间和 ScrollTrigger。
Unmount / Destroy	调用 ctx.revert()，终止该上下文中的所有动画和 ScrollTrigger，并还原内联样式。

不要在组件的 setup 阶段或根元素尚不存在时运行的同步顶层脚本中创建 GSAP 动画。请等待 onMounted / onMount（或等效阶段），确保容器 ref 已进入 DOM。

请勿

• ❌ 在组件挂载前创建补间动画或 ScrollTrigger（例如，在未使用 onMounted 的 setup 中）；此时 DOM 节点可能尚不存在。
• ❌ 使用不带 作用域 的选择器字符串（将容器作为第二个参数传给 gsap.context()），以免选择器匹配到组件外部的元素。
• ❌ 跳过清理；务必在 onUnmounted 中调用 ctx.revert()，或在 onMount 的返回函数中调用，以便在组件销毁时清除动画和 ScrollTrigger。
• ❌ 在每次渲染都会执行的组件主体中注册插件（虽然不会造成问题，但只是浪费）；应在应用层注册一次。

了解更多

• React 专用模式（useGSAP、contextSafe），请参阅 gsap-react 技能。