需要滚动触发动画、钉住区块、scrub 或视差时，用…

适用于实现滚动驱动动画：进入/离开视口触发 tween/timeline、把动画进度绑定滚动、固定区块、伪横向滚动和视差。

适用场景

解决思路

1. 加载脚本后调用一次 `gsap.registerPlugin(ScrollTrigger);` 注册插件。
2. 用 `gsap.to()` 或 timeline 的 `scrollTrigger` 配置把 tween/timeline 绑定到滚动位置；基础配置含 `trigger`、`start`、`end`、`toggleActions`。
3. `start`/`end` 格式为 `"triggerPosition viewportPosition"`，例如 `"top top"`、`"center center"`、`"bottom 80%"`；数字如 `500` 表示滚动条从顶部滚过 500px。
4. `start`/`end` 可用相对值：`"+=300"`（从 start 后再滚 300px）、`"+=100%"`（从 start 后再滚一个滚动容器高度）、`"max"`（最大滚动位置）。
5. 需要限制在页面边界内时，用 `clamp()`（v3.12+）包裹，如 `start: "clamp(top bottom)"`、`end: "clamp(bottom top)"`。
6. `start`/`end` 可写成函数，返回字符串或数字；函数接收 ScrollTrigger 实例；布局变化后调用 `ScrollTrigger.refresh()`。
7. `trigger` 用 String 或 Element 指定定义 ScrollTrigger 开始位置的元素；必需，或用简写 `scrollTrigger: ".selector"` 只设置 trigger。
8. `endTrigger` 在 end 需要基于不同于 trigger 的元素时使用。
9. `scrub` 用 Boolean 或 Number 把动画进度绑定到滚动；`true` 直接跟随，数字表示追赶当前滚动位置的秒数。
10. `toggleActions` 按顺序设置 `onEnter`、`onLeave`、`onEnterBack`、`onLeaveBack` 四个动作，可选 `"play"`、`"pause"`、`"resume"`、`"reset"`、`"restart"`、`"complete"`、`"reverse"`、`"none"`，默认 `"play none none none"`。
11. `pin` 在激活期间钉住元素；`true` 钉住 trigger；不要动画被钉住的元素本身，改为动画其子元素。
12. `pinSpacing` 默认 `true`，添加 spacer 防止布局塌陷；只有在外部单独处理布局时才用 `false` 或 `"margin"`。
13. `horizontal` 设 `true` 以支持横向滚动。
14. `scroller` 指定滚动容器（默认 viewport）；对可滚动 div 用 selector 或 element。
15. `markers` 开发时设为 `true` 查看触发位置，或传对象如 `{ startColor, endColor, fontSize, ... }`；生产环境移除或设为 `false`。
16. `once` 设 `true` 在到达 end 一次后 kill 该 ScrollTrigger（动画继续运行）。
17. `id` 设置唯一 id，便于用 `ScrollTrigger.getById(id)` 获取。
18. `refreshPriority` 数值越小越先 refresh；当 ScrollTrigger 创建顺序不是页面从上到下时设置它，使刷新顺序为页面顺序（页面上第一个 section 用更小数值）。
19. `toggleClass` 在激活时添加/移除 class；字符串作用于 trigger，或用 `{ targets: ".x", className: "active" }`。
20. `snap` 吸附到进度值；数字表示增量（如 `0.25`），数组表示指定值，`"labels"` 表示 timeline 标签，对象可写 `{ snapTo: 0.25, duration: 0.3, delay: 0.1, ease: "power1.inOut" }`。
21. `containerAnimation` 传 Tween/Timeline 实现伪横向滚动：ScrollTrigger 把纵向滚动绑定到该动画进度；注意基于 containerAnimation 的 ScrollTrigger 不支持 pinning 和 snapping。
22. 用 `onEnter`、`onLeave`、`onEnterBack`、`onLeaveBack` 在跨越 start/end 时执行回调；回调接收 ScrollTrigger 实例，可读 `progress`、`direction`、`isActive`、`getVelocity()`。
23. 用 `onUpdate`（进度变化时）、`onToggle`（active 翻转时）、`onRefresh`（重新计算后）、`onScrubComplete`（数字 scrub 完成时）执行回调。
24. 不绑定 tween 时用 `ScrollTrigger.create()` 创建独立 ScrollTrigger，使用相同配置，并通过回调自定义行为（如从 `self.progress` 更新 UI）。
25. 用 `ScrollTrigger.batch(triggers, vars)` 为每个目标创建一个 ScrollTrigger，并在短时间间隔内批处理回调；适合协调同一时间进入视口的元素动画（如 stagger），可替代 IntersectionObserver；返回 ScrollTrigger 实例数组。
26. 在 `batch()` 的 `triggers` 传 selector 文本（如 `".box"`）或元素数组。
27. 在 `batch()` 的 `vars` 传标准 ScrollTrigger 配置（start、end、once、callbacks 等）；不要传 `trigger`，也不要传 `animation`、`invalidateOnRefresh`、`onSnapComplete`、`onScrubComplete`、`scrub`、`snap`、`toggleActions` 等动画相关选项。
28. `batch()` 回调接收两个参数：`targets`（该间隔内触发回调的 trigger 元素数组）和 `scrollTriggers`（触发的 ScrollTrigger 实例数组）；可用它们读取 progress、direction 或调用 `kill()`。
29. `batch()` 可用 `interval`（收集每个批次的最大秒数，默认约一个 requestAnimationFrame；首个回调触发时开始计时，间隔结束或达到 batchMax 时发送批次）。
30. `batch()` 可用 `batchMax`（每批最大元素数；满时触发回调并开始下一批；传函数返回数字以适配响应式布局，函数在 refresh 时运行）。
31. 集成第三方平滑滚动或自定义滚动库时，用 `ScrollTrigger.scrollerProxy(scroller, vars)` 覆盖 ScrollTrigger 读取/写入滚动位置的方式；GSAP ScrollSmoother 是内置选项，不需要 proxy。
32. `scrollerProxy()` 的 `scroller` 传 selector 或 element（如 `"body"`、`".container"`）。
33. `scrollerProxy()` 的 `vars` 必须包含 `scrollTop` 和/或 `scrollLeft` 函数；每个函数带参数时是 setter，无参数时是 getter。
34. `scrollerProxy()` 可选传 `getBoundingClientRect` 返回 `{ top, left, width, height }`，当 scroller 实际矩形不是默认值时需要。
35. `scrollerProxy()` 可选传 `scrollWidth`/`scrollHeight` getter/setter 函数，当库暴露不同尺寸时使用。
36. `scrollerProxy()` 可选传 `fixedMarkers: true` 将 markers 视为 `position: fixed`，适用于 scroller 被平移导致 markers 移动错误时。
37. `scrollerProxy()` 可选传 `pinType: "fixed"` 或 `"transform"` 控制 pinning 应用方式；pins 抖动时用 `"fixed"`，pins 不粘住时用 `"transform"`。
38. 第三方 scroller 更新位置时，必须通知 ScrollTrigger：注册 `ScrollTrigger.update` 为监听器（如 `smoothScroller.addListener(ScrollTrigger.update)`）；否则计算会过期。
39. 用 `scrub` 实现滚动驱动进度：在 scrollTrigger 配置里设 `scrub: true` 或数字（如 `scrub: 1` 让动画平滑追赶）。
40. 用 `pin: true` 在滚动区间内钉住 trigger 元素；`end: "+=1000"` 可表示钉住 1000px 滚动距离。
41. 用 `pinSpacing: false` 仅在布局已单独处理时；默认 `true` 添加 spacer 防止固定定位导致布局塌陷。
42. 开发时用 `markers: true` 查看触发位置；生产移除或设 `markers: false`。
43. 用 timeline + ScrollTrigger 驱动时间轴：在 `gsap.timeline({ scrollTrigger: {...} })` 上配置，timeline 的 progress 通过 trigger 的 start/end 区间绑定滚动。
44. 实现伪横向滚动：先 pin 一个 section（trigger = 全视口 panel），再构建 tween 动画内部内容的 `x` 或 `xPercent` 使其向左移动，并在该 tween 上设 `ease: "none"`。
45. 伪横向滚动中，把 ScrollTrigger 附到该横向 tween 上，设置 `pin: true`、`scrub: true`。
46. 伪横向滚动中，要基于横向移动触发其他动画时，把 `containerAnimation` 设为该 tween，并让这些触发器的 `start`/`end` 基于横向移动（如 `"left center"`）。
47. 伪横向滚动中不要动画 trigger 元素本身；应动画子元素；如果 trigger 被移动，必须相应偏移 `start`/`end`。
48. DOM/layout 变化（新内容、图片、字体）影响触发位置后调用 `ScrollTrigger.refresh()` 重新计算位置；视口 resize 会自动调用（debounced 200ms）。
49. refresh 按创建顺序（或 `refreshPriority`）运行；按页面从上到下创建 ScrollTrigger，或设置 `refreshPriority` 使其按页面顺序刷新。
50. 移除动画元素或切换页面（如 SPA）时 kill 相关 ScrollTrigger：`ScrollTrigger.getAll().forEach(t => t.kill());` 或用 `ScrollTrigger.getById("my-id")?.kill();`。
51. React 中用 `useGSAP()` hook（`@gsap/react` NPM 包）自动清理，或在组件卸载的 cleanup（如 useEffect return）中手动 kill。
52. 在任何 ScrollTrigger 使用前只调用一次 `gsap.registerPlugin(ScrollTrigger)`。
53. DOM/layout 变化后调用 `ScrollTrigger.refresh()`；视口 resize 自动 debounced 200ms。
54. React 中用 `useGSAP()` hook，或手动用 `gsap.context()` 在 useEffect/useLayoutEffect cleanup 中 revert/cleanup 所有 ScrollTriggers 和 GSAP 动画。
55. 对滚动联动进度用 `scrub`，对离散播放/反向用 `toggleActions`；不要在同一 trigger 上同时用两者。
56. 伪横向滚动用 `containerAnimation` 时，横向 tween/timeline 必须用 `ease: "none"`。
57. 按页面出现顺序从上到下（scroll 0 → max）创建 ScrollTrigger；若必须动态/异步创建，设置 `refreshPriority` 使刷新顺序仍为从上到下（页面上第一个 section 用更小数字）。
58. 不要把 ScrollTrigger 放在 timeline 的子 tween 上；只放在 timeline 或顶层 tween 上。错误：`gsap.timeline().to(".a", { scrollTrigger: {...} })`；正确：`gsap.timeline({ scrollTrigger: {...} }).to(".a", { x: 100 })`。
59. 不要把带 ScrollTrigger 的动画嵌套在父 timeline 内；ScrollTrigger 只能存在于顶层动画。
60. 不要忘记在使用 ScrollTrigger 前调用 `gsap.registerPlugin(ScrollTrigger)`。
61. 不要在同一个 ScrollTrigger 上同时用 `scrub` 和 `toggleActions`；二选一，若都有则 `scrub` 生效。
62. 不要在 containerAnimation 的横向动画上使用 `ease` 非 `"none"`；会破坏滚动位置到横向位置的 1:1 映射。
63. 不要以随机或异步顺序创建 ScrollTrigger 而不设置 `refreshPriority`；刷新按创建顺序或 priority，错误顺序可能影响布局（如 pin spacing）。
64. 不要在生产环境保留 `markers: true`。
65. 不要忘记在影响触发位置的布局变化后调用 `refresh()`；视口 resize 自动处理，动态内容不会。

适用边界 · 注意事项

• 若不使用或不能引入 GSAP/ScrollTrigger 插件，则不适用。
• 基于 `containerAnimation` 的伪横向滚动 ScrollTrigger 不能使用 `pinning` 和 `snapping`。
• 同一个 ScrollTrigger 上不要同时期望 `scrub` 和 `toggleActions` 两种行为；二者冲突，`scrub` 优先。