gsap-framer-scroll-animation

GSAP & Framer Motion — 滚动动画技能

通过GitHub Copilot提示、即用型代码配方和深度API参考，实现生产级滚动动画。

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

快速库选择器

需求	使用
原生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组件、钩子要求或原生JS）。
5. 应用正确的工具（滚动与视口内元素），确保可访问性选项存在，且钩子不会导致无限重新渲染。

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时缓动效果会感觉不对
• GSAP React：使用@gsap/react中的useGSAP，不要使用普通的useEffect——它会自动清理ScrollTriggers
• GSAP调试：开发时添加markers: true；生产前移除
• Framer：useTransform的输出必须放入motion.*元素的style属性中，不能放入普通div
• Framer Next.js：在使用motion钩子的任何文件顶部始终添加'use client'
• 两者：仅对transform和opacity进行动画——避免width、height、box-shadow
• 可访问性：始终检查prefers-reduced-motion——每个参考文件中都有模式
• 高级精良：遵循premium-frontend-ui技能原则，关于动效时机、缓动曲线和克制——动画应增强而非压倒

Copilot提示技巧

• 提前给Copilot完整的选择器、基础图像和滚动范围——模糊的提示产生模糊的代码
• 对于GSAP，始终指定：选择器、start/end字符串、是否需要scrub或toggleActions
• 对于Framer，始终指定：使用哪个钩子（useScroll vs 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	创意理念、设计原则和美学指南——定义何时和为何进行动画