1实现原理 · 为什么它能做到
以一条主时间线为组织原则：单 playhead 加相对定位与标签，把多段动效编排成一个可 seek 的整体
skills/gsap-web/SKILL.md
Prefer one timeline over many independent tweens — it gives a single playhead, relative positioning, and easy reversal.
注：这正是后面 ?t=N 冻结帧取证能成立的前提：只有单一 playhead 才能稳定 seek。
滚动驱动靠 ScrollTrigger 的 start/end/pin/scrub 四要素，并强调 scrubbed tween 用 ease: none 才与滚动线性对应
skills/gsap-web/SKILL.md
start: "top top", // when trigger top hits viewport top
注：同节给 toggleActions 四个回调位的语义、markers 仅开发期使用、以及 ScrollTrigger.batch() 的批量化成本考量。
Lenis 平滑滚动与 ScrollTrigger 的抖动、漂移、断钉有同一根因（两个动画循环独立 tick），解法是一个循环：ticker 驱动 Lenis、每次 Lenis 滚动更新 ScrollTrigger
skills/gsap-web/SKILL.md
lenis.on("scroll", ScrollTrigger.update); // 1. update ScrollTrigger on every Lenis scroll
注：点明最容易漏的单位换算（gsap.ticker 传秒、lenis.raf 要毫秒，需乘 1000）与不要再自己开 rAF 这条最常见的错误。
文本揭示与布局过渡各有专用原语：SplitText（先等字体加载、行掩膜需 overflow:hidden、revert 还原 DOM）与 Flip（先取 state，再立即改 DOM，最后动画差值）
skills/gsap-web/SKILL.md
Always split AFTER web fonts load (`document.fonts.ready.then(...)`) to prevent wrong line breaks.
注：两者都给了不这么做会怎样 的具体失败模式，而不是只列 API。
SPA 与框架里必须做一次性清理：gsap.context() 或 useGSAP 的 ctx.revert() 杀掉 tween、ScrollTrigger 与内联样式，否则触发器泄漏、幽灵钉住堆叠
skills/gsap-web/SKILL.md
return () => ctx.revert(); // kills tweens, triggers, and reverts inline styles
注：与 Lenis 的 gsap.ticker.remove(update) 加 lenis.destroy() 一同构成卸载契约。
2核心能力
01时间线编排（相对定位参数、标签、from/to/fromTo、quickTo 高频跟随）
02ScrollTrigger 核心用法（pin 加 scrub、markers、toggleActions、batch、refresh）
03Lenis 与 Locomotive 平滑滚动和 ScrollTrigger 的单循环同步（含 scrollerProxy 差异与四个常见 bug）
04SplitText 文本揭示（行掩膜、字体加载时序、autoSplit、revert）
05Flip 布局过渡（网格与列表互换、卡片展开、跨容器迁移）
06缓动选择速查（power/back/elastic/none/steps/CustomEase）
07可交付模板与冻结 harness（CDN GSAP 加主时间线加 ?t=N，可直接当成品用）
08故障对照表（症状 → 成因，覆盖 Lenis 同步类现场问题）
3外部依赖
| 类型 | 依赖 |
|---|---|
| package | gsap 及插件 ScrollTrigger / SplitText / Flip（正文口径：3.12+ 全部免费含商用） |
| network | 交付模板从 cdnjs 取 GSAP（产物期引用，浏览器打开时拉取；执行期本 skill 不请求） |
| package | lenis（平滑滚动，与 ScrollTrigger 单循环同步；Locomotive 走 scrollerProxy 变体） |
| package | @gsap/react（useGSAP）与 React 清理路径 |
| cli | npx / Playwright（宿主侧截图工具）与仓库根 scripts/ 助手（seek-shot.sh、contact-sheet.sh 依赖 ffmpeg） |
4风险提醒 风险提醒：绿色 · 放心使用
风险提醒：绿色 · 放心使用
- 插件许可与版本声明无法在源码内核实（见 second_pass） — 3.12+ 全部免费含商用对商用决策有实质影响，但仓库内无依据文件；使用前应按 gsap 官方许可自行确认。
- 版本漂移敏感 — examples 模板钉 cdnjs 的 3.13.0，正文多处提到 3.12+ 与 3.13+ 的 API 差异（SplitText 类名、Flip absolute、ticker.lagSmoothing），跨版本行为变化会直接影响可运行性。
- Lenis 与 Locomotive 组合是高频故障面 — 即使有症状成因表，仍需正确区分 Lenis（走文档滚动，禁 scrollerProxy）与 Locomotive（必须 scrollerProxy 加 pinType）；配错会出现钉住断裂、滚动反向等看似引擎 bug 的现场。
- Packaged helper 路径以仓库根为基准，且 references 尾部带 iart.ai utm 推广链 — 单装时 scripts/seek-shot.sh 不可用；references/scrolltrigger-lenis.md 末行为 iart.ai 推广段（含 utm_term=gsap-web）。
风险提醒：绿色，放心使用。判级只依据 skill 自身目录（skills/gsap-web/ = SKILL.md + 0 字节 README.md + 2 份 references + examples/{hero-timeline.js, standalone-template.html}，find 全量核对）：无可执行入口被 agent 直接运行（两个 examples 是抄进交付物的示例与模板，无 shebang、无 CLI 用法）、无凭证读取、无写盘、执行期零外发。全目录 URL 仅两处，均在 examples/standalone-template.html 的 cdnjs script 标签（GSAP 3.13.0），按批4 口径属产物期引用，不判级，仅列出端点；examples/hero-timeline.js 的 import gsap from gsap 是用户工程依赖（注释已写 npm i gsap @gsap/react），同样非本 skill 外发。
5第二遍独立确认
- [unlocatable] GSAP 3.12+ 全部插件免费含商用这一许可声明是否可在源码内核实 — SKILL.md 首段声明 As of GSAP 3.12+, every plugin (ScrollTrigger, SplitText, Flip, MotionPath, MorphSVG, Draggable, Observer) is 100% free, including for commercial use. 但仓库内只有自身 MIT LICENSE，没有上游许可文件或链接，属外部事实声明，源码内不可复核，按文档声明记录。
- [ok] Lenis 同步的乘 1000 单位换算与不要再开 rAF 是否前后一致 — SKILL.md 三段互相印证：接线代码 gsap.ticker.add((t) => lenis.raf(t * 1000))、Critical 段明写 ticker 传秒而 raf 要毫秒、Common bugs 段把 leftover requestAnimationFrame(raf) loop 列为抖动根因；references 的调试清单第 1、2 条同样指向这两点。
- [ok] examples 里的两个文件是否真的可直接用 — hero-timeline.js 头注释给出所需 markup 与 CSS 前提（.line 需 overflow:hidden），并内置 document.readyState 自动启动；standalone-template.html 除 cdnjs GSAP 外无外部依赖，自带 ?t=N 冻结与 window.__ready，与 SKILL.md 的输出契约逐条对应。
- [discrepancy] Packaged helper 的路径基准 — SKILL.md 写 scripts/seek-shot.sh anim.html 0 1.5 3，但 scripts/ 在仓库根而非本 skill 目录（目录内只有 examples/ 与 references/），单装形态下该相对路径不成立；好在 examples/standalone-template.html 自带 harness，可自给自足。
6结论
适合：适合：① 滚动叙事（钉住加 scrub、视差、横向滚动、进度驱动）与复杂时序的 hero 或落地页；② 需要文字分行揭示或布局过渡（网格与列表互换、卡片展开）的实现；③ 已经或准备用 Lenis/Locomotive 做平滑滚动、需要与 ScrollTrigger 正确同步的工程；④ 想要带冻结 harness、能直接截图取证的零 build 交付模板。
不适合：不适合：① 只需要一两个简单 hover 或进场的界面（微交互应走 micro-interaction）；② 不能引入第三方动画库、只允许平台能力的项目（走 60fps-animation）；③ 需要无障碍优先的分级降级方案（本 skill 只给一句 reduced-motion 门控，细分档位在 accessible-animation）；④ 不想处理框架卸载生命周期的一次性页面。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-28
方式 A · 人下载镜像包下载 gsap-web.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agent1c57c75354a29de0…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库iart-ai / iart-ai/web-animation-skills
原始 GitHubiart-ai/web-animation-skills ↗
Stars28
最近推送2026-06-22
本 skill commit
b6dba3eb75许可MIT（仓库根 LICENSE 为 MIT License, Copyright (c) 2026 iart.ai；.claude-plugin/plugin.json 的 license 字段同为 MIT）
本站信息
收录日期2026-09-06
分类设计
侦查报告AI 侦查 · 2 遍 · 2026-09-06
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。