Communitygithub.com

gsap 動畫架構

針對高階網站的 GSAP 3 動畫架構 — 包含外掛註冊(ScrollTrigger、SplitText、Flip、Observer、Draggable、Inertia、CustomEase、MorphSVG、DrawSVG – 全部免費包含在公開 gsap 套件中)、與 React 整合的 useGSAP 作用域與清理機制、用於回應式與減少動態分支的 gsap.matchMedia、時間軸、滾動擦拭的固定序列、文字顯現、剪裁路徑/遮罩轉場、Flip 版面變形、水平滾動、視差、磁吸/游標效果以及頁面轉場。適用於任何 GSAP 或 ScrollTrigger 工作、任何滾動驅動或電影級動畫,以及當動畫在路由變更或視窗調整大小後發生洩漏、重複、卡頓或中斷時。

gsap 動畫架構 是什麼?

這是一個為高階網站設計的 GSAP 3 動畫架構技能,專門針對 AI 代理工具(如 Claude Code、Cursor、Codex 等)進行最佳化。它提供了一個完整的外掛註冊系統與 React 整合層,透過 `useGSAP` Hook 自動管理動畫的作用域、清理與洩漏預防,並支援 `gsap.matchMedia` 來實現回應式與減少動態(prefers-reduced-motion)的條件分支。 此技能的核心優勢在於其經過實戰驗證的架構與規則集,能解決 90% 在 React 中使用 GSAP 時常見的錯誤,包括動畫洩漏、重複、卡頓以及路由變更後的損壞。它附帶了完整的檔案範本(如 registry.ts、tokens.ts、可重複使用的文字顯現元件),以及經過 Playwright 測試套件驗證的參考範例(固定擦拭序列、Flip 濾鏡、游標效果等)。 AI 代理或開發人員可以依賴此技能來建立任何形式的滾動驅動或電影級動畫,從顯現場景、文字拆分效果、剪裁路徑轉場,到水平滾動、視差、磁吸/游標效果與頁面轉場。技能文件中明確提供了「目的性動畫檢查清單」,幫助團隊在加入動畫前思考其溝通意圖,並確保減少動態模式下的可理解性。 此技能適用於所有 GSAP 支援的平台,重點是與 React 專案的深度整合。它強制使用 `useGSAP` 而非原始的 `useEffect`,並提供了包括 Lenis 平滑滾動在內的完整工作流程標準化建議。

相容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/jakyherr05-hash/Claude-code-skill/tree/HEAD/plugins/premium-web-studio/skills/gsap-motion

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 錯誤的規則

  1. 每個動畫都位於 useGSAP(() => {...}, { scope: ref }) 內部。該 context 會在元件卸載時反轉所有 tween、ScrollTriggers、SplitText 以及 matchMedia 分支。事件處理器的動畫使用 contextSafe。
  2. 切勿在模組層級或在未經反轉的普通 useEffect 中建立 ScrollTriggers。切勿將 ScrollTrigger.killAll() 當作清理策略。
  3. 每個區段使用一個 gsap.matchMedia(),包含 motion/reduce(以及桌面/行動裝置)條件。初始隱藏狀態設定在動態分支內部,因此無 JavaScript 與減少動態的使用者會看到最終內容。
  4. 嚴格模式安全: useGSAP 處理 React 18/19 的雙重呼叫。使用洩漏檢查驗證:在導航離開和返回後,ScrollTrigger.getAll().length 會回到基準值。
  5. 版面變更後重新整理: 字型載入後(document.fonts.ready.then(() => ScrollTrigger.refresh()))、清單篩選後以及路由內容掛載後。觸發器的值若從版面計算得出,請設定 invalidateOnRefresh: true。
  6. 正確固定: 固定一個內部包裝器,保留 pinSpacing,給予一個不依賴網路字型的 min-height: 100svh,並搭配 Lenis 使用 anticipatePin: 1。每個體驗使用一個固定效果;疊加的固定效果會讓使用者混淆。
  7. 動畫化便宜的屬性: transform、opacity、clip-path;CSS 變數僅限於小型子樹。避免在擦拭時間軸中使用 width/height/top/left,並在寫入之前讀取版面(GSAP 會批次處理自己的寫入)。
  8. 僅在動畫進行時設定 will-change,且僅限於少數圖層。

配方

references/recipes.md 包含經過測試或記錄的模式,用於:電影級開場序列、SplitText 顯現(字元/單字/行、遮罩)、剪裁路徑與遮罩轉場、固定擦拭敘事、水平滾動區段(containerAnimation)、視差圖層、Flip 狀態變形、Observer 驅動的手勢區段、Draggable + Inertia 輪播、磁吸按鈕、游標跟隨器、SVG 變形/繪製、影像扭曲移交給 WebGL、頁面轉場,以及搭配 WebGL 相機的 3D 滾動。

references/react-lifecycle.md 涵蓋路由變更、視窗調整大小、內容變更以及除錯洩漏。

目的性動畫檢查清單(動畫化之前)

  • 這個動畫要傳達什麼(階層、因果、狀態、品牌素材)?如果什麼都沒有,就刪掉它。
  • 它是標誌性時刻,還是應該保持低調?
  • 減少動態模式會顯示什麼替代內容?(必須維持完全可理解。)
  • 行動版表達方式是什麼?(懸停效果需要觸控替代方案;固定效果會變短。)
  • 頁面建立了多少個 ScrollTriggers?將清單寫入規格中,以便 QA 可以斷言。

相關技能