gsap

已弃用：已由官方 GSAP skills 取代，https://github.com/greensock/gsap-skills（gsap-core、gsap-timeline、gsap-scrolltrigger、gsap-plugins、gsap-react、gsap-utils、gsap-performance、gsap-frameworks）。原始内容请参阅此仓库的历史记录。

GSAP（GreenSock Animation Platform）

概述

GSAP 是一个强大且速度极快的 JavaScript 动画库，可用于为任何内容添加动画（CSS 属性、SVG、canvas、React 组件）。它专为现代 Web 性能打造，并能开箱即用地处理跨浏览器差异。

核心组件：

• gsap.to()、gsap.from()、gsap.fromTo()：基础补间动画。
• Timeline：使用 gsap.timeline() 对多个补间动画进行编排。
• Plugins：添加额外功能（例如，用于滚动动画的 ScrollTrigger、用于 FLIP 动画的 Flip）。

---

安装

参考：GSAP 文档、React 指南

使用场景	包
核心	gsap
React / Next.js（推荐）	gsap、@gsap/react

使用包管理器添加（参见 npm）。GSAP 提供专用的 React Hook（useGSAP）来管理清理和上下文。

---

核心用法

基础补间动画

import gsap from "gsap";

// Animate to a state
gsap.to(".box", { x: 100, duration: 1, ease: "power2.inOut" });

// Animate from a state
gsap.from(".box", { opacity: 0, y: 50, duration: 1, stagger: 0.1 });

时间线

时间线非常适合编排一系列动画。

const tl = gsap.timeline({ repeat: -1, yoyo: true });

tl.to(".box1", { x: 100, duration: 1 })
  .to(".box2", { y: 50, duration: 0.5 }, "-=0.5") // Start 0.5s early
  .to(".box3", { rotation: 360 });

缓动函数

自定义动画的感觉。

• 标准："none"、"power1" 到 "power4"、"back"、"bounce"、"circ"、"elastic"、"expo"、"sine"。
• 添加 .in、.out 或 .inOut（例如，"power2.inOut"）。

---

React 用法（useGSAP）

使用 React（或 Next.js）时，始终使用 @gsap/react 包及其 useGSAP Hook，而不要使用标准的 useEffect。它会自动处理清理，避免内存泄漏和严格模式下的重复触发。

import { useRef } from "react";
import gsap from "gsap";
import { useGSAP } from "@gsap/react";

gsap.registerPlugin(useGSAP);

export default function App() {
  const container = useRef<HTMLDivElement>(null);

  useGSAP(() => {
    // gsap code here...
    // All animations created here are automatically reverted on cleanup!
    gsap.to(".box", { x: 360, duration: 2 });
  }, { scope: container }); // Scope allows selecting elements only inside this container

  return (
    <div ref={container}>
      <div className="box">Box</div>
    </div>
  );
}

---

常用插件

插件可扩展 GSAP 的核心功能。使用前必须先注册。

ScrollTrigger

在滚动时为元素添加动画、固定区块，或将动画与滚动条关联。

import gsap from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";

gsap.registerPlugin(ScrollTrigger);

gsap.to(".box", {
  scrollTrigger: {
    trigger: ".box",
    start: "top center", // When top of element hits center of viewport
    end: "bottom top", 
    scrub: true, // Tie animation strictly to scrollbar
    pin: true,
  },
  x: 500,
});

其他值得关注的插件：

• Flip：流畅地为状态或布局发生变化的元素添加动画。
• Observer：规范化事件（滚动、触摸、指针），以支持基于意图的交互。
• Draggable：让元素可拖动、旋转或抛掷。
• SplitText：将 HTML 文本拆分为字符、单词或行，以便进行精细动画（高级版）。
• DrawSVG：直观地为 SVG 描边添加动画（高级版）。
• MorphSVG：将任意 SVG 路径变形为另一个路径（高级版）。

---

常见模式与最佳实践

• 注册：始终提前注册插件（例如，gsap.registerPlugin(ScrollTrigger, useGSAP)）。
• React 严格模式：依赖 useGSAP()，避免 React 18 严格模式下 useEffect 重复调用创建重复动画。
• 变换：使用 GSAP 快捷属性（x、y、rotation、scale、autoAlpha），而非标准的 transform 或 opacity 字符串，以获得更好的性能和准确性。
• FOUC（无样式内容闪烁）：对于初始加载动画，使用 CSS 隐藏元素（visibility: hidden，而非 display: none），并使用 gsap.from() 或 gsap.set(..., { autoAlpha: 0 })。

---

更多资源

• reference.md — GSAP 官方文档、核心 API、插件、React 集成 — 可编入索引
• 官方文档：https://gsap.com/docs/v3/
• React 指南：https://gsap.com/resources/React
• ScrollTrigger：https://gsap.com/docs/v3/Plugins/ScrollTrigger