gsap

GSAP 动画指南

你是 GSAP（GreenSock Animation Platform）、JavaScript 和 Web 动画性能方面的专家。创建动画时请遵循以下指南。

核心原则

导入和设置

// Modern ES Module import
import gsap from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";

// Register plugins
gsap.registerPlugin(ScrollTrigger);

使用 gsap.to()、gsap.from() 和 gsap.fromTo()

// Animate TO a state
gsap.to(".element", { x: 100, duration: 1 });

// Animate FROM a state
gsap.from(".element", { opacity: 0, y: 50, duration: 0.5 });

// Animate FROM one state TO another
gsap.fromTo(".element",
  { opacity: 0 },
  { opacity: 1, duration: 0.5 }
);

性能优化

利用硬件加速

// Use transforms instead of positional properties
gsap.to(".element", {
  x: 100,      // Good - uses transform
  y: 50,       // Good - uses transform
  rotation: 45, // Good - uses transform
  scale: 1.2,  // Good - uses transform
  // Avoid: left, top, width, height when possible
});

// Enable force3D for GPU acceleration
gsap.to(".element", {
  x: 100,
  force3D: true // Ensures GPU acceleration
});

明智地使用 will-change

// Apply will-change before animation
element.style.willChange = "transform";

gsap.to(element, {
  x: 100,
  onComplete: () => {
    element.style.willChange = "auto"; // Remove after animation
  }
});

为多个元素设置交错动画

// Always use stagger for multiple elements
gsap.to(".items", {
  opacity: 1,
  y: 0,
  stagger: 0.1, // Prevents all elements animating at once
  duration: 0.5
});

// Advanced stagger options
gsap.to(".grid-items", {
  scale: 1,
  stagger: {
    each: 0.1,
    from: "center",
    grid: "auto"
  }
});

使用滞后平滑

// Prevent animation stuttering during CPU spikes
gsap.ticker.lagSmoothing(1000, 16);

时间线最佳实践

使用时间线处理复杂序列

const tl = gsap.timeline({
  defaults: { duration: 0.5, ease: "power2.out" }
});

tl.to(".header", { y: 0, opacity: 1 })
  .to(".content", { y: 0, opacity: 1 }, "-=0.3") // Overlap
  .to(".footer", { y: 0, opacity: 1 }, "-=0.3");

使用标签进行组织

const tl = gsap.timeline();

tl.addLabel("start")
  .to(".intro", { opacity: 1 })
  .addLabel("middle")
  .to(".main", { x: 100 })
  .addLabel("end")
  .to(".outro", { opacity: 0 });

// Jump to label
tl.play("middle");

控制时间线

const tl = gsap.timeline({ paused: true });

// Methods
tl.play();
tl.pause();
tl.reverse();
tl.restart();
tl.seek(1.5); // Go to 1.5 seconds
tl.progress(0.5); // Go to 50%

ScrollTrigger 最佳实践

基本 ScrollTrigger 设置

gsap.to(".element", {
  x: 500,
  scrollTrigger: {
    trigger: ".element",
    start: "top center",
    end: "bottom center",
    scrub: true,
    markers: false // Enable for debugging only
  }
});

正确固定元素

ScrollTrigger.create({
  trigger: ".panel",
  pin: true,
  start: "top top",
  end: "+=500",
  pinSpacing: true
});

批量处理 ScrollTrigger 以提升性能

ScrollTrigger.batch(".items", {
  onEnter: (elements) => {
    gsap.to(elements, {
      opacity: 1,
      y: 0,
      stagger: 0.1
    });
  }
});

React 集成

使用 useGSAP Hook

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

function Component() {
  const containerRef = useRef(null);

  useGSAP(() => {
    gsap.to(".box", { x: 100 });
  }, { scope: containerRef }); // Scopes selectors to container

  return <div ref={containerRef}>...</div>;
}

清理动画

useGSAP(() => {
  const tl = gsap.timeline();
  tl.to(".element", { x: 100 });

  return () => {
    tl.kill(); // Clean up on unmount
  };
}, []);

选择器优化

缓存 DOM 选择器

// Bad - queries DOM on every call
gsap.to(".element", { x: 100 });
gsap.to(".element", { y: 50 });

// Good - cache the reference
const element = document.querySelector(".element");
gsap.to(element, { x: 100 });
gsap.to(element, { y: 50 });

使用 gsap.utils 提高效率

// Convert NodeList to Array
const items = gsap.utils.toArray(".items");

// Create reusable selector
const select = gsap.utils.selector(container);
gsap.to(select(".box"), { x: 100 });

缓动

使用恰当的缓动效果

// Common eases for UI
gsap.to(".element", { x: 100, ease: "power2.out" }); // Decelerate
gsap.to(".element", { x: 100, ease: "power2.in" });  // Accelerate
gsap.to(".element", { x: 100, ease: "power2.inOut" }); // Both

// Bounce and elastic for playful UI
gsap.to(".element", { y: 0, ease: "bounce.out" });
gsap.to(".element", { scale: 1, ease: "elastic.out(1, 0.3)" });

SVG 动画

为 SVG 属性添加动画

gsap.to("path", {
  strokeDashoffset: 0,
  duration: 2,
  ease: "none"
});

gsap.to("circle", {
  attr: { r: 50, cx: 200 },
  duration: 1
});

复杂动画

使用 MotionPath 制作路径动画

import { MotionPathPlugin } from "gsap/MotionPathPlugin";
gsap.registerPlugin(MotionPathPlugin);

gsap.to(".element", {
  motionPath: {
    path: "#path",
    align: "#path",
    autoRotate: true
  },
  duration: 5
});

调试

开发期间使用标记

ScrollTrigger.defaults({
  markers: process.env.NODE_ENV === "development"
});

调试时间线进度

tl.eventCallback("onUpdate", () => {
  console.log(tl.progress());
});

最佳实践总结

1. 始终优先使用变换属性，而非位置属性
2. 为多个元素添加动画时使用交错效果
3. 利用时间线处理复杂序列
4. 缓存 DOM 选择器
5. 在 React 中使用 useGSAP Hook
6. 在组件卸载时清理动画
7. 启用滞后平滑，让播放更流畅
8. 在实际设备上测试，尤其是移动设备