gsap-framer-scroll-animation

GSAP 与 Framer Motion — 滚动动画技能

生产级滚动动画，包含 GitHub Copilot 提示词、即用型代码配方和深入 API 参考。

设计配套技能： 本技能提供滚动驱动动效的技术实现。 至于应指导如何以及何时进行动画的创意理念、设计原则和高级美学， 请始终交叉参考 premium-frontend-ui 技能。 二者共同构成完整方案：premium-frontend-ui 决定做什么和为什么； 本技能交付怎么做。

快速选择库

需求	使用
原生 JS、Webflow、Vue	GSAP
固定（pinning）、横向滚动、复杂时间线	GSAP
React / Next.js、声明式风格	Framer Motion
whileInView 入场动画	Framer Motion
在同一个 Next.js 应用中同时使用两者	参见 references 中的说明

阅读相关参考文件以获取完整配方和 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); // MUST call before any ScrollTrigger usage

Framer Motion（Motion v12，2025）

npm install motion   # new package name since mid-2025
# or: npm install framer-motion  — still works, same API

import { motion, useScroll, useTransform, useSpring } from 'motion/react';
// legacy: import { motion } from 'framer-motion'  — also valid

工作流

1. 解读用户意图，判断 GSAP 还是 Framer Motion 最合适。
2. 阅读 references/ 中的相关参考文档，了解详细 API 和模式。
3. 如果尚未安装所需包，建议安装。
4. 为动画结构实现脚手架，遵循所要求的格式（React 组件、hook 要求或原生 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. Scrub / 滚动联动（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 激活时缓动会显得不对
• GSAP React：使用来自 @gsap/react 的 useGSAP，绝不要用普通的 useEffect——它会自动清理 ScrollTrigger
• GSAP 调试：开发期间添加 markers: true；生产环境前移除
• Framer：useTransform 的输出必须放入 motion.* 元素的 style prop，而不是普通 div
• Framer Next.js：任何使用 motion hook 的文件顶部务必添加 'use client'
• 两者通用：只对 transform 和 opacity 做动画——避免 width、height、box-shadow
• 无障碍：务必检查 prefers-reduced-motion——模式参见各参考文件
• 高级打磨：遵循 premium-frontend-ui 技能原则，把握动效时机、缓动曲线和克制——动画应起到增强作用，绝不喧宾夺主

Copilot 提示技巧

• 预先给 Copilot 提供完整选择器、基础图像和滚动范围——模糊的提示词产出模糊的代码
• 对于 GSAP，务必说明：选择器、start/end 字符串、你想要 scrub 还是 toggleActions
• 对于 Framer，务必说明：使用哪个 hook（useScroll 还是 whileInView）、offset 值、要变换什么
• 请求 /fix 时粘贴确切的错误消息——有真实错误时 Copilot 的修复效果会好得多
• 在 Copilot Chat 中使用 @workspace 作用域，让它读取你现有的组件结构

参考文件

文件	内容
references/gsap.md	完整 ScrollTrigger API 参考、10 个配方、React（useGSAP）、Lenis、matchMedia、无障碍
references/framer.md	完整 useScroll / useTransform API、8 个配方、变体、Motion v12 说明、Next.js 技巧

相关技能

技能	关系
premium-frontend-ui	创意理念、设计原则与美学指南 —— 定义何时以及为何要添加动画