gsap-frameworks

GSAP 與 Vue、Svelte 及其他框架

何時使用此技能

在 Vue（或 Nuxt）、Svelte（或 SvelteKit）或其他使用生命週期（mounted/unmounted）的元件框架中撰寫或審查 GSAP 程式碼時使用。對於 React，請使用 gsap-react（useGSAP hook、gsap.context()）。

相關技能： 補間動畫與時間軸請使用 gsap-core 和 gsap-timeline；滾動動畫請使用 gsap-scrolltrigger；React 請使用 gsap-react。

原則（所有框架）

• 建立補間動畫和 ScrollTrigger 必須在元件的 DOM 可用之後（例如 onMounted、onMount）。
• 在 unmount（或同等）清理中終止或還原它們，確保不會在已卸載的節點上執行，也不會造成記憶體洩漏。
• 限定選擇器範圍到元件根元素，讓 .box 等選擇器只匹配該元件內的元素，而非頁面其他部分。

Vue 3（Composition API）

請參閱 examples/vue/ 中的可執行 Vite + Vue 3 專案，示範這些模式。

使用 onMounted 在元件掛載到 DOM 後執行 GSAP。使用 onUnmounted 進行清理。

import { onMounted, onUnmounted, ref } from "vue";
import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
gsap.registerPlugin(ScrollTrigger); // 每個應用程式註冊一次，例如在 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> 和 ref 的相同概念：

<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>

Nuxt 4

請參閱 examples/nuxt/ 中的可執行 Nuxt 4 專案，示範外掛註冊、延遲載入和 SSR 安全模式。

使用可複用的 composable 來註冊 GSAP 外掛，並延遲載入應用程式中不常使用的外掛：

// composables/useGSAP.ts
import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";

const PLUGINS = [
  "CSSRulePlugin",
  "CustomBounce",
  "CustomEase",
  "CustomWiggle",
  "Draggable",
  "DrawSVGPlugin",
  "EaselPlugin",
  "EasePack",
  "Flip",
  "GSDevTools",
  "InertiaPlugin",
  "MorphSVGPlugin",
  "MotionPathHelper",
  "MotionPathPlugin",
  "Observer",
  "Physics2DPlugin",
  "PhysicsPropsPlugin",
  "PixiPlugin",
  "ScrambleTextPlugin",
  "ScrollSmoother",
  "ScrollToPlugin",
  "ScrollTrigger",
  "SplitText",
  "TextPlugin",
] as const;

type Plugins = (typeof PLUGINS)[number];

// 為了動態載入所有 GSAP 外掛
const pluginMap = {
  CustomEase: () => import("gsap/CustomEase"),
  Draggable: () => import("gsap/Draggable"),
  CSSRulePlugin: () => import("gsap/CSSRulePlugin"),
  EaselPlugin: () => import("gsap/EaselPlugin"),
  EasePack: () => import("gsap/EasePack"),
  Flip: () => import("gsap/Flip"),
  MotionPathPlugin: () => import("gsap/MotionPathPlugin"),
  Observer: () => import("gsap/Observer"),
  PixiPlugin: () => import("gsap/PixiPlugin"),
  ScrollToPlugin: () => import("gsap/ScrollToPlugin"),
  ScrollTrigger: () => import("gsap/ScrollTrigger"),
  TextPlugin: () => import("gsap/TextPlugin"),
  DrawSVGPlugin: () => import("gsap/DrawSVGPlugin"),
  Physics2DPlugin: () => import("gsap/Physics2DPlugin"),
  PhysicsPropsPlugin: () => import("gsap/PhysicsPropsPlugin"),
  ScrambleTextPlugin: () => import("gsap/ScrambleTextPlugin"),
  CustomBounce: () => import("gsap/CustomBounce"),
  CustomWiggle: () => import("gsap/CustomWiggle"),
  GSDevTools: () => import("gsap/GSDevTools"),
  InertiaPlugin: () => import("gsap/InertiaPlugin"),
  MorphSVGPlugin: () => import("gsap/MorphSVGPlugin"),
  MotionPathHelper: () => import("gsap/MotionPathHelper"),
  ScrollSmoother: () => import("gsap/ScrollSmoother"),
  SplitText: () => import("gsap/SplitText"),
} as const;

type PluginMap = typeof pluginMap;
type Plugins = keyof PluginMap;

// 解析給定鍵的模組類型，然後選取與鍵同名的具名匯出
// 這樣可以在程式碼編輯器中獲得自動補全的型別定義
type PluginModule<K extends Plugins> = Awaited<ReturnType<PluginMap[K]>>;
type PluginExport<K extends Plugins> = PluginModule<K>[K & keyof PluginModule<K>];

export default function () {
  // 在此處註冊所有你想要的 GSAP 外掛
  gsap.registerPlugin(ScrollTrigger);

  /*
    如果你想延遲載入應用程式中不常使用的外掛
    （例如只在少數元件或單一路由中使用），可以使用此方法
  */
  async function lazyLoadPlugin<K extends Plugins>(plugin: K): Promise<PluginExport<K>> {
    const loader = pluginMap[plugin];
    const m = await loader();
    const p = (m as any)[plugin];
    gsap.registerPlugin(p);
    return p;
  }

  return {
    gsap,
    ScrollTrigger,
    lazyLoadPlugin,
  };
}

在元件中透過 useGSAP() 存取：

const { gsap, ScrollTrigger, lazyLoadPlugin } = useGSAP();

• ✅ useGSAP() 提供型別安全的 gsap 實例和延遲載入方法。
• ✅ 延遲載入任何外掛（SplitText、MorphSVG 等），這些外掛在應用程式中不常使用，以減少初始套件大小。
• ✅ 在元件中使用 gsap.context(scope) 和 onUnmounted → ctx.revert()，與 Vue 3 相同。

Svelte

使用 onMount 在 DOM 準備好後執行 GSAP。使用 onMount 的回傳清理函式（或追蹤 context 並在反應式區塊/元件銷毀時清理）來還原。Svelte 5 使用不同的生命週期；相同原則：在「mounted」中建立，在「destroyed」中還原。

<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) — .box 只在 containerRef 內搜尋。
• ❌ 在元件中執行 gsap.to(".box", ...) 而沒有 context scope，可能會影響其他實例或頁面其他部分。

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()，以終止該 context 中的所有動畫和 ScrollTrigger，並還原內聯樣式。

不要在元件的 setup 或同步頂層腳本（在根元素存在之前執行）中建立 GSAP 動畫。請等待 onMounted / onMount（或同等），確保容器 ref 已在 DOM 中。

禁止事項

• ❌ 在元件掛載前建立補間或 ScrollTrigger（例如在 setup 中但沒有 onMounted）；DOM 節點可能尚未存在。
• ❌ 使用沒有 scope 的選擇器字串（將容器作為第二個參數傳遞給 gsap.context()），以免選擇器匹配元件外部的元素。
• ❌ 跳過清理；務必在 onUnmounted / onMount 的回傳中呼叫 ctx.revert()，以便在元件銷毀時終止動畫和 ScrollTrigger。
• ❌ 在每次渲染都會執行的元件主體中註冊外掛（雖然不會造成傷害，但浪費資源）；請在應用程式層級註冊一次。

了解更多

• gsap-react 技能：React 專用模式（useGSAP、contextSafe）。