gsap-react

gsap-react 技能概覽

gsap-react 是用來做什麼的

gsap-react 是 GSAP 官方提供給 React 與以 React 為基礎的框架（例如 Next.js）的技能。它能幫你用正確的 React 安全模式來做動畫：useGSAP()、作用域選擇器、gsap.context()，以及自動清理。當你想在元件裡加入動態效果，又不想跟重新渲染、卸載，或 DOM 選取問題硬碰硬時，就適合用 gsap-react 技能。

誰適合使用它

這個技能適合已經懂 React、想要穩定動畫設定的前端工程師，而不是給你從頭學動畫的入門教材。當你在判斷 React app 要不要用 GSAP、動畫在路由切換後壞掉，或是需要了解 gsap-react 的安裝與整合流程時，它特別有用。

它和其他做法有什麼不同

它最大的價值在於 React 專屬的安全性。它不會只教你寫一個一般的 useEffect() 動畫再手動清理，而是引導你改用 useGSAP() 和作用域目標，讓動畫行為更可預期。它也能幫你避開常見、但會阻礙導入的錯誤：未做作用域限制的選擇器、沒有註冊外掛，以及和 SSR 相關的混淆。

如何使用 gsap-react 技能

安裝 GSAP 與 React 套件

進行 gsap-react install 時，先把這兩個套件加到你的應用中：

npm install gsap
npm install @gsap/react

接著，在使用 useGSAP() 或其他 GSAP 程式碼之前先註冊外掛：

import { useGSAP } from "@gsap/react";
gsap.registerPlugin(useGSAP);

如果跳過註冊，這個 hook 的行為就不會如預期。

把模糊的目標，改寫成可用的提示詞

最好的 gsap-react 用法，始於具體的動畫目標，而不是「讓它看起來更好」。提示詞最好包含：元件類型、哪些內容要動、何時開始、是否要重複，以及這個效果是否必須在路由切換後仍然有效，或在卸載時自動清理。

一個好的提示詞可以像這樣：

• 「在 Next.js client component 中，讓三張卡片在掛載時滑入，並限制在這個容器內。」
• 「把這段 useEffect() 的 GSAP 動畫改成 useGSAP()，並加入清理與 refs。」
• 「加入 hover 與 scroll-triggered 動態效果，但 selectors 要維持在元件作用域內。」

先閱讀正確的檔案

先從 SKILL.md 開始，再查看 repo copy 中定義行為與限制的部分。在這個技能裡，可用的路徑不長，所以先讀核心說明，再看任何連結範例或周邊文件（如果有）。對 gsap-react 來說，最關鍵的判斷點在 When to Use This Skill、Installation，以及 Prefer the useGSAP() Hook 這幾節。

採用對 React 安全的工作流程

預設流程是：匯入 useGSAP、註冊外掛、建立一個 ref、把 selectors 限制在該 ref 內，然後把動畫程式碼放進 hook。這比直接用全域 document 選擇器或不加作用域的 timelines 更好。如果你需要稍後才觸發的 callback，請使用 contextSafe，這樣延遲互動也能正確清理。

gsap-react 技能 FAQ

每個 React 裡的 GSAP 動畫都需要 gsap-react 嗎？

不需要。如果動畫很小，而且你在技術棧的其他部分已經有成熟解法，這個技能可能就不是必需的。當程式碼會碰到元件生命週期、清理、作用域 DOM 定位，或 React／Next.js 的框架特定行為時，才適合用 gsap-react。

這和一般提示詞有什麼不同？

一般提示詞可能也能產生可運作的動畫程式碼，但 gsap-react 會加入更偏向正式專案的 React 整合規則：外掛註冊、useGSAP()、作用域選擇器，以及清理行為。這能減少除錯時間，也讓輸出更容易直接重用在實際的 app 程式碼中。

gsap-react 對新手友善嗎？

友善，只要使用者能描述元件與想要的動態效果。它不是動畫理論的入門課，而是一個實用的 gsap-react 指南，幫你從粗略的 UI 想法走到安全的 React 程式碼。新手若能提供元件結構與預期觸發條件，通常會得到最好的結果。

什麼情況下不該用它？

不要把 gsap-react 用在非 React 框架，或你需要的是不依賴特定函式庫的動畫答案時。對 Vue、Svelte 與其他技術棧，應改用該框架對應的 GSAP 技能。如果你只需要核心的 tween 或 timeline 語法，其他 GSAP 技能可能更合適。

如何改善 gsap-react 技能

提供結構，不要只給意圖

要讓 gsap-react 的輸出更好，關鍵是具體。請提供元件標記、你已經有的 selectors 或 refs，以及精確的觸發條件。「讓 hero 動起來」太模糊；「在首次渲染時讓標題淡入、CTA 滑入、功能卡片依序 stagger 出現」才足以讓技能產出可直接使用的程式碼。

提前說明會影響實作的限制

請盡早說明 SSR、路由切換、reduced motion，以及清理需求。這些限制會決定答案該用 useGSAP()、client component、作用域 refs，還是另一種動畫方式。如果你的 app 是 Next.js，請在提示詞中明確指出。

先檢查第一版輸出的作用域問題

常見失敗模式包括：選擇器沒有做作用域限制、動畫太早執行，以及程式碼忽略了元件卸載。如果第一版用的是像 .box 這類大範圍 selector，卻沒有 scope，請要求改寫成以 ref 為作用域。若 callback 會延後觸發，後續再要求加上 contextSafe 的處理。

依照你真正要的動態效果逐步迭代

第一輪之後，建議一次只調一個變數：時間、easing、stagger、trigger，或清理行為。好的 gsap-react 使用流程是：先實作基本動畫、在元件中測試，再針對需要的部分做精準調整，例如「在 mobile 上不要那麼強烈」或「把觸發條件改成只在 hover 時生效」。