gsap 動畫架構 是做什麼的?
驗證基準(2026-11-15)
[email protected]是目前 npm 上的最新版本。它的授權欄位顯示為「Standard 'no charge' license」(gsap.com/standard-license):免費供商業網站使用,包括客戶作品。唯一的禁止用途是建置與 Webflow 競爭的無程式碼視覺動畫建置工具。所有外掛都隨附於公開套件中:ScrollTrigger、ScrollSmoother、SplitText、Flip、Observer、Draggable、InertiaPlugin、CustomEase、CustomBounce、CustomWiggle、MorphSVGPlugin、DrawSVGPlugin、MotionPathPlugin、ScrambleTextPlugin、ScrollToPlugin、Physics2D、PhysicsProps、GSDevTools 等。@gsap/[email protected]提供了useGSAP。- 在新專案前重新確認:
npm view gsap version license與ls node_modules/gsap/*.js。 - 使用 ScrollSmoother 或 Lenis,切勿兩者並用。本工作室標準化使用 Lenis(
lenis-scroll技能)。
架構(將 assets/ 複製到 src/motion/)
| 檔案 | 角色 |
|---|---|
assets/registry.ts | 註冊外掛一次,建立專案的 CustomEases,設定預設值,ScrollTrigger.config({ ignoreMobileResize: true })。所有程式碼都從此處匯入 gsap。 |
assets/tokens.ts | 動態記號(持續時間、緩動函式、交錯)鏡像自 ANIMATION_SPECIFICATION.md + prefersReducedMotion() |
assets/lit.ts | 範例可重複使用的文字基礎元件:使用 aria:'auto'、autoSplit 以及回傳 tween 的 onSplit 的 SplitText。根據品牌調整顯現方式(點亮、遮罩、滑入…)。 |
assets/useReducedMotion.ts | 用於 DOM 層級切換(例如渲染靜態步驟而非固定)的即時 prefers-reduced-motion Hook |
assets/examples/*.tsx | 來自參考示範的經過測試的模式:固定擦拭序列(Method)、Flip 濾鏡(ScheduleIndex)、quickTo 驅動的互動效果(TheHour)、單次顯現效果(Rooms)、路由轉場遮罩(Router) |
這些檔案是此儲存庫中 demo/ 的經過驗證的實作,並由其 Playwright 測試套件(跨路由清理、減少動態、滾動同步)所驗證。
可預防 React 中 90% GSAP 錯誤的規則
- 每個動畫都位於
useGSAP(() => {...}, { scope: ref })內部。該 context 會在元件卸載時反轉所有 tween、ScrollTriggers、SplitText 以及 matchMedia 分支。事件處理器的動畫使用contextSafe。 - 切勿在模組層級或在未經反轉的普通
useEffect中建立 ScrollTriggers。切勿將ScrollTrigger.killAll()當作清理策略。 - 每個區段使用一個
gsap.matchMedia(),包含motion/reduce(以及桌面/行動裝置)條件。初始隱藏狀態設定在動態分支內部,因此無 JavaScript 與減少動態的使用者會看到最終內容。 - 嚴格模式安全:
useGSAP處理 React 18/19 的雙重呼叫。使用洩漏檢查驗證:在導航離開和返回後,ScrollTrigger.getAll().length會回到基準值。 - 版面變更後重新整理: 字型載入後(
document.fonts.ready.then(() => ScrollTrigger.refresh()))、清單篩選後以及路由內容掛載後。觸發器的值若從版面計算得出,請設定invalidateOnRefresh: true。 - 正確固定: 固定一個內部包裝器,保留
pinSpacing,給予一個不依賴網路字型的min-height: 100svh,並搭配 Lenis 使用anticipatePin: 1。每個體驗使用一個固定效果;疊加的固定效果會讓使用者混淆。 - 動畫化便宜的屬性: transform、opacity、clip-path;CSS 變數僅限於小型子樹。避免在擦拭時間軸中使用 width/height/top/left,並在寫入之前讀取版面(GSAP 會批次處理自己的寫入)。
- 僅在動畫進行時設定
will-change,且僅限於少數圖層。
配方
references/recipes.md 包含經過測試或記錄的模式,用於:電影級開場序列、SplitText 顯現(字元/單字/行、遮罩)、剪裁路徑與遮罩轉場、固定擦拭敘事、水平滾動區段(containerAnimation)、視差圖層、Flip 狀態變形、Observer 驅動的手勢區段、Draggable + Inertia 輪播、磁吸按鈕、游標跟隨器、SVG 變形/繪製、影像扭曲移交給 WebGL、頁面轉場,以及搭配 WebGL 相機的 3D 滾動。
references/react-lifecycle.md 涵蓋路由變更、視窗調整大小、內容變更以及除錯洩漏。
目的性動畫檢查清單(動畫化之前)
- 這個動畫要傳達什麼(階層、因果、狀態、品牌素材)?如果什麼都沒有,就刪掉它。
- 它是標誌性時刻,還是應該保持低調?
- 減少動態模式會顯示什麼替代內容?(必須維持完全可理解。)
- 行動版表達方式是什麼?(懸停效果需要觸控替代方案;固定效果會變短。)
- 頁面建立了多少個 ScrollTriggers?將清單寫入規格中,以便 QA 可以斷言。