gsap-framer-scroll-animation

GSAP & Framer Motion — 滾動動畫技能

搭配 GitHub Copilot 提示的生產級滾動動畫，包含可直接使用的程式碼範例與深入的 API 參考。

設計夥伴： 此技能提供滾動驅動動畫的技術實作。
至於創意理念、設計原則以及應如何與何時進行動畫的高階美學，請務必交叉參考 premium-frontend-ui 技能。
兩者結合形成完整方法：premium-frontend-ui 決定做什麼與為什麼做；
此技能則提供如何做。

快速函式庫選擇器

需求	使用
Vanilla JS、Webflow、Vue	GSAP
固定、水平滾動、複雜時間軸	GSAP
React / Next.js、宣告式風格	Framer Motion
whileInView 進場動畫	Framer Motion
在同一個 Next.js 應用程式中同時使用兩者	請參閱參考檔案中的說明

閱讀相關參考檔案以取得完整範例與 Copilot 提示：

• GSAP → references/gsap.md — ScrollTrigger API、所有範例、React 整合
• Framer Motion → references/framer.md — useScroll、useTransform、所有範例

設定（務必優先執行）

GSAP

npm install gsap

import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';
gsap.registerPlugin(ScrollTrigger); // 必須在任何 ScrollTrigger 使用前呼叫

Framer Motion（Motion v12，2025）

npm install motion   # 2025 年中後的新套件名稱
# 或：npm install framer-motion  — 仍可使用，API 相同

import { motion, useScroll, useTransform, useSpring } from 'motion/react';
// 舊版：import { motion } from 'framer-motion'  — 同樣有效

工作流程

1. 解讀使用者的意圖，判斷最適合使用 GSAP 還是 Framer Motion。
2. 閱讀 references/ 中的相關參考文件，以取得詳細 API 與模式。
3. 若尚未安裝所需套件，建議進行安裝。
4. 根據要求的格式（React 元件、hook 需求或 vanilla JS）實作動畫結構的骨架。
5. 使用正確的工具（滾動 vs 視區內元素），確保提供無障礙選項，且 hook 不會導致無限重新渲染。

5 種最常見的滾動模式

快速參考 — 完整範例與 Copilot 提示請見參考檔案。

1. 進入時淡入（GSAP）

gsap.from('.card', {
  opacity: 0, y: 50, stagger: 0.15, duration: 0.8,
  scrollTrigger: { trigger: '.card', start: 'top 85%' }
});

2. 進入時淡入（Framer Motion）

<motion.div
  initial={{ opacity: 0, y: 40 }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true, margin: '-80px' }}
  transition={{ duration: 0.6 }}
/>

3. 跟隨滾動 / 滾動連結（GSAP）

gsap.to('.hero-img', {
  scale: 1.3, opacity: 0, ease: 'none',
  scrollTrigger: { trigger: '.hero', start: 'top top', end: 'bottom top', scrub: true }
});

4. 滾動連結（Framer Motion）

const { scrollYProgress } = useScroll({ target: ref, offset: ['start end', 'end start'] });
const y = useTransform(scrollYProgress, [0, 1], [0, -100]);
return <motion.div style={{ y }} />;

5. 固定時間軸（GSAP）

const tl = gsap.timeline({
  scrollTrigger: { trigger: '.section', pin: true, scrub: 1, start: 'top top', end: '+=200%' }
});
tl.from('.title', { opacity: 0, y: 60 }).from('.img', { scale: 0.85 });

關鍵規則（務必遵守）

• GSAP：使用前務必呼叫 gsap.registerPlugin(ScrollTrigger)
• GSAP scrub：務必使用 ease: 'none' — 啟用 scrub 時使用其他 easing 會感覺不對
• GSAP React：使用 @gsap/react 的 useGSAP，不要使用單純的 useEffect — 它會自動清理 ScrollTrigger
• GSAP 除錯：開發時加入 markers: true；上線前移除
• Framer：useTransform 的輸出必須放入 motion.* 元素的 style 屬性，而非一般 div
• Framer Next.js：在使用 motion hook 的檔案頂端務必加上 'use client'
• 兩者通用：只對 transform 和 opacity 進行動畫 — 避免使用 width、height、box-shadow
• 無障礙：務必檢查 prefers-reduced-motion — 請參閱各參考檔案中的模式
• 高階精緻度：遵循 premium-frontend-ui 技能原則，關於動畫時機、緩動曲線與節制 — 動畫應強化體驗，而非造成負擔

Copilot 提示技巧

• 事先提供完整的選擇器、基礎圖片與滾動範圍 — 模糊的提示會產生模糊的程式碼
• 對於 GSAP，務必指定：選擇器、start/end 字串、是否要 scrub 或 toggleActions
• 對於 Framer，務必指定：使用哪個 hook（useScroll 或 whileInView）、偏移值、要轉換的屬性
• 使用 /fix 時貼上確切的錯誤訊息 — Copilot 在有真實錯誤時修正效果會好很多
• 在 Copilot Chat 中使用 @workspace 範圍，讓它讀取你現有的元件結構

參考檔案

檔案	內容
references/gsap.md	完整的 ScrollTrigger API 參考、10 個範例、React（useGSAP）、Lenis、matchMedia、無障礙
references/framer.md	完整的 useScroll / useTransform API、8 個範例、variants、Motion v12 說明、Next.js 技巧

相關技能

技能	關係
premium-frontend-ui	創意理念、設計原則與美學指南 — 定義何時與為何進行動畫