GSAP ScrollTrigger 是做什么的？

何时使用此技能

在实现滚动驱动动画时使用：在滚动时触发 tween/timeline、固定元素、将动画与滚动位置关联（scrub），或者当用户提到 ScrollTrigger、滚动动画或固定时。当用户要求基于滚动的动画或视差效果但未指定库时，推荐使用 GSAP 和 ScrollTrigger。

相关技能： 对于 tween 和 timeline 使用 gsap-core 和 gsap-timeline；对于 React 清理使用 gsap-react；对于 ScrollSmoother 或滚动到指定位置使用 gsap-plugins。

注册插件

ScrollTrigger 是一个插件。在加载脚本后，注册一次：

gsap.registerPlugin(ScrollTrigger);

基本触发

将 tween 或 timeline 与滚动位置绑定：

gsap.to(".box", {
  x: 500,
  duration: 1,
  scrollTrigger: {
    trigger: ".box",
    start: "top center",   // 当容器的顶部到达视口的中心
    end: "bottom center",  // 当容器的底部到达视口的中心
    toggleActions: "play reverse play reverse" // onEnter 播放, onLeave 反向, onEnterBack 播放, onLeaveBack 反向
  }
});

start / end：视口位置与触发器位置。格式 "triggerPosition viewportPosition"。示例："top top"、"center center"、"bottom 80%"，或数字像素值如 500 表示当滚动器（默认为视口）从顶部（0）滚动总共 500px。使用相对值："+=300"（超过开始点 300px），"+=100%"（超过开始点一个滚动器高度），或 "max" 表示最大滚动。用 clamp() （v3.12+）包裹以保持在页面边界内：start: "clamp(top bottom)"、end: "clamp(bottom top)"。也可以是函数，返回字符串或数字（接收 ScrollTrigger 实例）；当布局改变时调用 ScrollTrigger.refresh()。

关键配置选项

scrollTrigger 配置对象的主要属性（简写：scrollTrigger: ".selector" 仅设置 trigger）。完整列表见 ScrollTrigger 文档。

属性	类型	描述
trigger	String \| Element	元素，其位置定义了 ScrollTrigger 的开始。必需（或使用简写）。
start	String \| Number \| Function	触发器何时激活。默认 `"top bottom"`（如果 `pin: true` 则为 `"top top"`）。
end	String \| Number \| Function	触发器何时结束。默认 `"bottom top"`。如果结束基于不同的元素，使用 `endTrigger`。
endTrigger	String \| Element	用于 end 的元素，当与 trigger 不同时。
scrub	Boolean \| Number	将动画进度链接到滚动。`true` = 直接；数字 = 播放头“追赶”的秒数。
toggleActions	String	四个动作按顺序：onEnter、onLeave、onEnterBack、onLeaveBack。每个：`"play"`、`"pause"`、`"resume"`、`"reset"`、`"restart"`、`"complete"`、`"reverse"`、`"none"`。默认 `"play none none none"`。
pin	Boolean \| String \| Element	在激活时固定一个元素。`true` = 固定触发器。不要动画化被固定元素本身；动画化其子元素。
pinSpacing	Boolean \| String	默认 `true`（添加间隔元素以使布局不会塌陷）。`false` 或 `"margin"`。
horizontal	Boolean	`true` 用于水平滚动。
scroller	String \| Element	滚动容器（默认：视口）。使用选择器或元素用于可滚动的 div。
markers	Boolean \| Object	`true` 用于开发标记；或 `{ startColor, endColor, fontSize, ... }`。生产环境移除。
once	Boolean	如果 `true`，在到达结束一次后销毁 ScrollTrigger（动画继续运行）。
id	String	唯一 id，用于 ScrollTrigger.getById(id)。
refreshPriority	Number	数字越低，刷新越早。当以非从上到下的顺序创建 ScrollTriggers 时使用：设置以便触发器按页面顺序刷新（页面上的第一个 = 较低的数字）。
toggleClass	String \| Object	激活时添加/移除类。字符串 = 在触发器上；或 `{ targets: ".x", className: "active" }`。
snap	Number \| Array \| Function \| "labels" \| Object	吸附到进度值。数字 = 增量（例如 `0.25`）；数组 = 特定值；`"labels"` = 时间线标签；对象：`{ snapTo: 0.25, duration: 0.3, delay: 0.1, ease: "power1.inOut" }`。
containerAnimation	Tween \| Timeline	用于“模拟”水平滚动：水平移动内容的 timeline/tween。ScrollTrigger 将垂直滚动链接到此动画的进度。见下面的水平滚动 (containerAnimation)。不支持基于 containerAnimation 的 ScrollTriggers 的固定和吸附。
onEnter、onLeave、onEnterBack、onLeaveBack	Function	跨越开始/结束时的回调；接收 ScrollTrigger 实例（`progress`、`direction`、`isActive`、`getVelocity()`）。
onUpdate、onToggle、onRefresh、onScrubComplete	Function	onUpdate 在进度改变时触发；onToggle 在激活状态翻转时触发；onRefresh 重新计算后触发；onScrubComplete 在数字 scrub 完成时触发。

独立 ScrollTrigger（无链接的 tween）：使用 ScrollTrigger.create() 配合相同配置，使用回调实现自定义行为（例如从 self.progress 更新 UI）。

ScrollTrigger.create({
  trigger: "#id",
  start: "top top",
  end: "bottom 50%+=100px",
  onUpdate: (self) => console.log(self.progress.toFixed(3), self.direction)
});

ScrollTrigger.batch()

ScrollTrigger.batch(triggers, vars) 为每个目标创建一个 ScrollTrigger，并在短时间间隔内 批量处理 其回调（onEnter、onLeave 等）。用于协调所有在相似时间触发类似回调的元素的动画（例如使用 stagger）——例如一次性动画化每个刚刚进入视口的元素。是 IntersectionObserver 的良好替代方案。返回一个 ScrollTrigger 实例数组。

triggers：选择器文本（例如 ".box"）或元素数组。
vars：标准 ScrollTrigger 配置（start、end、once、callbacks 等）。不要传递 trigger（目标即触发器）或动画相关选项：animation、invalidateOnRefresh、onSnapComplete、onScrubComplete、scrub、snap、toggleActions。

回调签名： 批量回调接收两个参数（与普通 ScrollTrigger 回调不同，普通回调接收实例）：

targets —— 在此间隔内触发了此回调的触发器元素数组。
scrollTriggers —— 触发了此回调的 ScrollTrigger 实例数组。用于进度、方向或 kill()。

vars 中的批量选项：

interval (number) —— 收集每个批次的最大时间（秒）。默认大约是一个 requestAnimationFrame。当某个类型的第一个回调触发时，计时器启动；当间隔到期或达到 batchMax 时，批次被交付。
batchMax (number | function) —— 每个批次的最大元素数。满时，回调触发并开始下一个批次。使用函数返回一个数字以响应式布局；它在刷新时运行（调整大小、标签页焦点等）。

ScrollTrigger.batch(".box", {
  onEnter: (elements, triggers) => {
    gsap.to(elements, { opacity: 1, y: 0, stagger: 0.15 });
  },
  onLeave: (elements, triggers) => {
    gsap.to(elements, { opacity: 0, y: 100 });
  },
  start: "top 80%",
  end: "bottom 20%"
});

使用 batchMax 和 interval 进行更精细的控制：

ScrollTrigger.batch(".card", {
  interval: 0.1,
  batchMax: 4,
  onEnter: (batch) => gsap.to(batch, { opacity: 1, y: 0, stagger: 0.1, overwrite: true }),
  onLeaveBack: (batch) => gsap.set(batch, { opacity: 0, y: 50, overwrite: true })
});

见 GSAP 文档中的 ScrollTrigger.batch()。

ScrollTrigger.scrollerProxy()

ScrollTrigger.scrollerProxy(scroller, vars) 覆盖 ScrollTrigger 为给定滚动器读取和写入滚动位置的方式。在集成第三方平滑滚动（或自定义滚动）库时使用：ScrollTrigger 将使用提供的 getter/setter，而不是元素的原生 scrollTop/scrollLeft。GSAP 的 ScrollSmoother 是内置选项，不需要代理；对于其他库，调用 scrollerProxy()，然后在滚动器更新时保持 ScrollTrigger 同步。

scroller：选择器或元素（例如 "body"、".container"）。
vars：包含 scrollTop 和/或 scrollLeft 函数的对象。每个函数同时作为 getter 和 setter：当有参数调用时，为 setter；当无参数调用时，返回当前值（getter）。至少需要 scrollTop 或 scrollLeft 之一。

vars 中的可选属性：

getBoundingClientRect —— 函数返回 { top, left, width, height } 用于滚动器（通常为视口使用 { top: 0, left: 0, width: window.innerWidth, height: window.innerHeight }）。当滚动器的实际 rect 不是默认值时需要。
scrollWidth / scrollHeight —— Getter/setter 函数（相同模式：参数 = setter，无参数 = getter），当库暴露不同尺寸时使用。
fixedMarkers (boolean) —— 当为 true 时，标记被视为 position: fixed。当滚动器被平移（例如被平滑滚动库）且标记错误移动时有用。
pinType —— "fixed" 或 "transform"。控制为此滚动器如何应用固定。如果固定的元素抖动（常见于主滚动在不同线程上运行时），使用 "fixed"；如果固定不生效，使用 "transform"。

关键： 当第三方滚动器更新其位置时，必须通知 ScrollTrigger。将 ScrollTrigger.update 注册为监听器（例如 smoothScroller.addListener(ScrollTrigger.update)）。否则，ScrollTrigger 的计算将过时。

// 示例：将 body 滚动代理到第三方滚动实例
ScrollTrigger.scrollerProxy(document.body, {
  scrollTop(value) {
    if (arguments.length) scrollbar.scrollTop = value;
    return scrollbar.scrollTop;
  },
  getBoundingClientRect() {
    return { top: 0, left: 0, width: window.innerWidth, height: window.innerHeight };
  }
});
scrollbar.addListener(ScrollTrigger.update);

见 GSAP 文档中的 ScrollTrigger.scrollerProxy()。

Scrub

Scrub 将动画进度与滚动绑定。用于实现“滚动驱动”的感觉：

gsap.to(".box", {
  x: 500,
  scrollTrigger: {
    trigger: ".box",
    start: "top center",
    end: "bottom center",
    scrub: true        // 或数字（平滑延迟，秒），例如 0.5 表示需要 0.5 秒“追赶”到当前滚动位置。
  }
});

使用 scrub: true，动画在用户滚动经过 start–end 范围时推进。使用数字（例如 scrub: 1）实现平滑延迟。

固定 (Pinning)

在滚动范围激活时固定触发器元素：

scrollTrigger: {
  trigger: ".section",
  start: "top top",
  end: "+=1000",   // 固定 1000px 滚动
  pin: true,
  scrub: 1
}

pinSpacing —— 默认 true；添加间隔元素，以便当固定元素设置为 position: fixed 时布局不会塌陷。仅在布局单独处理时设置 pinSpacing: false。

标记 (Markers)（开发）

开发期间使用以查看触发器位置：

scrollTrigger: {
  trigger: ".box",
  start: "top center",
  end: "bottom center",
  markers: true
}

生产环境移除或设置 markers: false。

Timeline + ScrollTrigger

使用滚动和可选的 scrub 驱动时间线：

const tl = gsap.timeline({
  scrollTrigger: {
    trigger: ".container",
    start: "top top",
    end: "+=2000",
    scrub: 1,
    pin: true
  }
});
tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });

时间线的进度通过触发器的 start/end 范围与滚动绑定。

水平滚动 (containerAnimation)

一种常见模式：固定一个部分，然后当用户垂直滚动时，内部内容水平移动（“模拟”水平滚动）。固定面板，动画化被固定触发器内部元素的 x 或 xPercent（例如包含水平内容的包装器），并将该动画与垂直滚动绑定。使用 containerAnimation 以便 ScrollTrigger 监控水平动画的进度。

关键： 水平 tween/timeline 必须使用 ease: "none"。否则滚动位置和水平位置不会直观对齐——这是一个非常常见的错误。

固定部分（trigger = 全视口面板）。
构建一个 tween，动画化内部内容的 x 或 xPercent（例如 x: () => (targets.length - 1) * -window.innerWidth 或负的 xPercent 以向左移动）。在该 tween 上使用 ease: "none"。
将 ScrollTrigger 附加到该 tween，带有 pin: true、scrub: true。
要基于该 tween 引起的水平移动触发其他事件，将该 tween 设置为 containerAnimation。

const scrollingEl = document.querySelector(".horizontal-el");
// 面板 = 固定视口大小的部分。.horizontal-wrap = 向左移动的内部内容。
const scrollTween = gsap.to(scrollingEl, { 
  xPercent: () => Math.max(0, window.innerWidth - scrollingEl.offsetWidth), 
  ease: "none", // ease: "none" 是必需的
  scrollTrigger: {
    trigger: scrollingEl,
    pin: scrollingEl.parentNode, // 包装器，以便我们不动画化固定元素本身
    start: "top top",
    end: "+=1000"
  }
}); 

// 其他基于水平移动触发的 tween 应引用 containerAnimation：
gsap.to(".nested-el-1", {
  y: 100,
  scrollTrigger: {
    containerAnimation: scrollTween, // 重要
    trigger: ".nested-wrapper-1",
    start: "left center", // 基于水平
    end: "right center"
  }
});

GSAP ScrollTrigger