1实现原理 · 为什么它能做到
把一个插件当成一等主题：先用「注册」建立前置条件，再按配置面（trigger/start/end/scrub/pin…）给出一张 20+ 项的可查表。
skills/gsap-scrolltrigger/SKILL.md
ScrollTrigger is a plugin. After loading the script, register it once:
注：为什么能实现宣称功能：ScrollTrigger 不是核心引擎的一部分，必须先 gsap.registerPlugin(ScrollTrigger) 才能把 scrollTrigger 配置挂到 tween/timeline 上；skill 把这一步放在最前，避免模型直接写 scrollTrigger 配置导致静默失效。
把 start/end 的字符串语法讲成「触发点 vs 视口点」的坐标模型，并给出 clamp()/相对值/函数三种进阶形态。
skills/gsap-scrolltrigger/SKILL.md
**start** / **end**: viewport position vs. trigger position. Format `"triggerPosition viewportPosition"`.
注：这里在做什么：把 "top center" 这类短语法还原成可推理的模型（元素哪个位置碰上视口哪个位置），这样模型能自造合法组合（"bottom 80%"、clamp(top bottom)、"+=300"、"max"），而不是死记示例。
batch() 用一批 ScrollTrigger + 时间窗聚合回调，替代 IntersectionObserver 手写批处理：一次给到本轮进入视口的全部元素。
skills/gsap-scrolltrigger/SKILL.md
**ScrollTrigger.batch(triggers, vars)** creates one ScrollTrigger per target and **batches** their callbacks
注：关键细节也写清了：批回调签名是两个参数（targets, scrollTriggers）而非普通 ST 回调的单实例；batchMax 可为函数以适配响应式；且禁止传 trigger/scrub/snap 等冲突选项。
scrollerProxy() 给出与第三方平滑滚动库共存的接法：用自定义 getter/setter 覆盖 scrollTop/scrollLeft，并把 ScrollTrigger.update 注册为滚动监听。
skills/gsap-scrolltrigger/SKILL.md
**Critical:** When the third-party scroller updates its position, ScrollTrigger must be notified.
注：还给了 pinType（fixed/transform）与 fixedMarkers 这类只有在「滚动发生在别的线程/被 transform 位移」时才会暴露的排障旋钮——这是纯文档难抄的实操经验。
「假横向滚动」模式被拆成四步固定配方，并把 ease: "none" 列为硬约束（否则滚动位置与横向位置不同步）。
skills/gsap-scrolltrigger/SKILL.md
The container animation must use **ease: "none"**.
注：配方：pin 面板 → 动画内部 x/xPercent（ease none）→ ST 挂该 tween（pin+scrub）→ 其它元素用 containerAnimation 引用它。同时声明两个限制：containerAnimation 场景不能用 pin 与 snap。
生命周期纪律前置：refresh 的自动/手动边界 + 创建顺序/refreshPriority + kill 清理，防止 SPA 里遗留实例在陈旧节点上跑。
skills/gsap-scrolltrigger/SKILL.md
Create ScrollTriggers in the order they appear on the page (top to bottom, scroll 0 → max).
注：具体规则：resize 自动 refresh（去抖 200ms）但动态内容不会自动，需手动 refresh()；创建顺序影响 pin spacing，乱序须设 refreshPriority；删除元素/换页要 kill。
把「scrub 与 toggleActions 二选一」写成显式互斥，并告知同时存在时 scrub 胜出——这是查询式排障里最常见的困惑。
skills/gsap-scrolltrigger/SKILL.md
❌ Use **scrub** and **toggleActions** together on the same ScrollTrigger; choose one behavior. If both exist, **scrub** wins.
注：与 gsap-performance 的「scrub: 1 降低滚动期工作量」呼应，但本 skill 侧重语义正确性。
2核心能力
01基础触发：trigger + start/end + toggleActions 四动作（onEnter/onLeave/onEnterBack/onLeaveBack）
02scrub 滚动联动：true 直连或数值（秒）做“追赶”平滑
03pin 固定 + pinSpacing 占位（含「不要动被固定的元素本身」的约束）
04batch() 批量进入/离开的聚合回调（interval / batchMax / 双参签名）
05scrollerProxy() 与第三方平滑滚动库对接（含 scrollTop/scrollLeft getter-setter 双态语义）
06containerAnimation 假横向滚动（配 ease:none 硬约束与 pin/snap 不可用）
07snap 对齐（数值/数组/"labels"/对象含 duration-delay-ease）与 toggleClass、markers、refreshPriority、id/getById
08刷新与销毁：refresh()/refreshPriority 次序、以及 getAll()/getById() 的 kill 清理
3外部依赖
| 类型 | 依赖 |
|---|---|
| package | gsap/ScrollTrigger（插件，须 registerPlugin） |
| network | GSAP 官方 ScrollTrigger 文档 |
| network | batch() 官方文档 |
| network | scrollerProxy() 官方文档 |
4风险提醒 风险提醒：绿色 · 放心使用
风险提醒：绿色 · 放心使用
- pin/scrollerProxy 会真实改动页面布局与滚动行为 — pin 插入 spacer、scrollerProxy 接管 scrollTop 读写；用错（如 pin 动被固定元素、proxy 忘了通知 update）会造成滚动错位或抖动，必须真机验证。
- 清理纪律依赖开发者执行 — SPA 中换页/卸载不 kill 会留下绑定在陈旧节点上的实例；React 侧需配合 gsap-react 的 useGSAP 或 ctx.revert() 才能自动回收。
- containerAnimation 模式能力受限 — 官方限制（skill 已声明）：该模式下 pin 与 snap 不可用，且必须 ease:none、触发元素需偏移 start/end——用错会得到「不同步」的假横向滚动。
- 版本敏感 — clamp() 需 v3.12+、SplitText/onSplit 等新 API 属 v3.13+；本分析只对 pin aed9cfd 负责，跨版本使用需自行核对 API。
风险提醒：绿色，放心使用。纯指令型 skill：目录内仅 SKILL.md（18,390 B），无脚本、无网络外发、无凭证读取、无文件写入；三条外链均为 gsap.com 官方文档。注意点：skill 会引导 agent 在用户页面里创建大量 ScrollTrigger 实例（pin/scrollerProxy 会改动 DOM 与滚动容器行为），若清理纪律被忽略可能留下粘连元素/滚动错位——这是能力使用边界，不是安全风险。
5第二遍独立确认
- [ok] 目录资产面：仅 SKILL.md — skills/gsap-scrolltrigger/ 下唯一文件 SKILL.md（18,390 B）；无 scripts/、references/、数据文件。
- [ok] external_deps 逐条核实调用点 — registerPlugin(ScrollTrigger) 代码块、三条 gsap.com URL（文档链接、batch()、scrollerProxy()）均在文件内逐字命中，无自造端点。
- [ok] 「ease: none 是硬约束」是否有原文支撑 — 原文两处强调：配方第 2 步「Use **ease: "none"** on that tween」与 Caveats「The container animation must use **ease: "none"**.」，并解释原因是 1:1 映射会被缓动破坏。
- [ok] batch 回调签名描述（两参数）是否属实 — 原文明确「Batched callbacks receive **two** parameters (unlike normal ScrollTrigger callbacks, which receive the instance)」，与 GSAP 官方 batch 行为一致。
- [ok] scrollerProxy getter/setter 双态语义描述 — 原文「called **with** an argument, it is a setter; called **with no** argument → getter」并给出 arguments.length 判定的示例代码，符合官方 API。
- [ok] 安全反例搜索（隐藏脚本/网络/凭证） — 对该文件 token 扫描：curl/wget/fetch(/XMLHttpRequest/exec(/child_process/process.env/.env/API_KEY/secret 全零命中；URL 仅 3 条 gsap.com。
- [ok] 与 gsap-performance / gsap-react 的表述是否冲突 — 三者对 scrub、refresh、React 清理的说法一致（performance 提出去抖 refresh、react 提供 useGSAP 自动清理），无自相矛盾。
- [ok] 元数据与 pin — frontmatter license MIT；本地 HEAD = aed9cfd3277740755f6bfc1155c7aa645403b760；GitHub API stars 15326 / pushed_at 2026-07-29T17:36:08Z（晚于 pin，结论不跨版本）。
6结论
适合：适合任何做滚动叙事/视差/固定章节/横向滚动的 GSAP 项目，尤其需要 pin、scrub、batch 或与第三方平滑滚动库共存的复杂页面；也适合作为团队 ScrollTrigger 规范的速查底稿。React/Vue/Svelte 侧配合 gsap-react / gsap-frameworks 处理生命周期。
不适合：不适合简单的「元素进入视口就淡入」——用 IntersectionObserver 或 CSS 可能更轻（skill 自己把 batch 定位为 IntersectionObserver 的替代而非必需）；不适合不用 GSAP 的滚动方案（如纯 CSS scroll-driven animations）；不适合期望 skill 自带可视化调试工具的场景（调试在 gsap-plugins 的 GSDevTools）。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-15
方式 A · 人下载镜像包下载 gsap-scrolltrigger.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agentd77050ca6e9970e0…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库greensock / greensock/gsap-skills
原始 GitHubgreensock/gsap-skills ↗
Stars15326
最近推送2026-07-29
本 skill commit
aed9cfd327许可MIT（仓库根 LICENSE，Copyright (c) 2026 GreenSock；GitHub API spdx_id=MIT；每个 SKILL.md frontmatter 亦写 license: MIT）
本站信息
收录日期2026-09-06
分类设计
侦查报告AI 侦查 · 2 遍 · 2026-09-06
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。