GSAP 是一套用于网页动画的 JavaScript 库，本文档是面向 HyperFrames 的 GSAP 动画参考，整理其核心 API 与使用要点。
一、核心补间方法
- gsap.to(targets, vars)：从当前状态动画到 vars，最常用。
- gsap.from(targets, vars)：从 vars 动画到当前状态，用于入场。
- gsap.fromTo(targets, fromVars, toVars)：显式指定起点与终点。
- gsap.set(targets, vars)：立即应用（duration 为 0）。 属性名始终使用驼峰式（如 backgroundColor、rotationX）。
二、常用 vars
- duration：秒，默认 0.5。
- delay：开始前延迟秒数。
- ease：如 "power1.out"（默认）、"power3.inOut"、"back.out(1.7)"、"elastic.out(1, 0.3)"、"none"。
- stagger：数字 0.1，或对象 { amount: 0.3, from: "center" }、{ each: 0.1, from: "random" }。
- overwrite：false（默认）、true 或 "auto"。
- repeat：数字或 -1 表示无限；yoyo 配合 repeat 交替方向。
- onComplete、onStart、onUpdate：回调。
- immediateRender：from()/fromTo() 默认 true；对同一属性与元素的后续补间可设为 false 以避免覆盖。
三、变换与 CSS 优先使用 GSAP 的变换别名而非原始 transform 字符串：x/y/z 对应 translateX/Y/Z（px）；xPercent/yPercent 对应百分比平移；scale、scaleX、scaleY；rotation 对应 rotate（度）；rotationX、rotationY 为 3D 旋转；skewX、skewY；transformOrigin 对应 transform-origin。autoAlpha 优先于 opacity，为 0 时同时设置 visibility: hidden。支持 CSS 变量（如 "--hue": 180）。svgOrigin 仅用于 SVG，表示全局 SVG 坐标空间原点，不要与 transformOrigin 同时使用。方向性旋转如 "360_cw"、"-170_short"、"90_ccw"。clearProps 可设为 "all" 或逗号分隔列表，在完成时移除内联样式。相对值如 "+=20"、"-=10"、"*=2"。
四、函数式取值 可为属性传入函数，如 x: (i, target, targets) => i * 50，配合 stagger 使用。
五、缓动 内置缓动包括 power1–power4、back、bounce、circ、elastic、expo、sine，每种都有 .in、.out、.inOut。
六、默认值 可用 gsap.defaults({ duration: 0.6, ease: "power2.out" }) 设置全局默认。
七、控制补间 补间返回值可调用 pause()、play()、reverse()、kill()、progress(0.5)、time(0.2) 等方法。
八、gsap.matchMedia()（响应式与无障碍） 仅在媒体查询匹配时运行设置，不再匹配时自动还原。示例中通过 context.conditions 获取 isDesktop 与 reduceMotion，据此调整 rotation 与 duration。
九、时间线 创建：const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } })，随后链式添加 .to()。 位置参数（第三个参数）控制放置：绝对时间 1；相对 "+=0.5"（结束后）、"-=0.2"（结束前）；标签 "intro"、"intro+=0.3"；对齐 "<"（与上一个同时开始）、">"（上一个结束后）、"<0.2"（上一个开始后 0.2 秒）。 标签：tl.addLabel("intro", 0)，可在位置参数中使用标签，tl.play("outro")、tl.tweenFromTo("intro", "outro")。 时间线选项：paused: true 创建后暂停，需调用 .play() 启动；repeat、yoyo 作用于整条时间线；defaults 合并进每个子补间。 嵌套：可创建 master 与 child 时间线，用 master.add(child, 0) 加入。 播放控制：tl.play()、pause()、reverse()、restart()、time(2)、progress(0.5)、kill()。
十、性能 优先动画 transform 与 opacity（x、y、scale、rotation、opacity 留在合成器上），避免用 width、height、top、left 实现同样效果。will-change: transform 只加在真正动画的元素上。频繁更新用 gsap.quickTo()，示例中为 x、y 分别创建 quickTo 并在 mousemove 中调用。用 stagger 替代多个带手动延迟的补间。清理：暂停或杀死屏幕外动画。
十一、按需加载的参考 references/effects.md：即插即用效果，如打字机文本、音频可视化；需要现成效果模式时阅读。
十二、最佳实践 使用驼峰属性名；优先变换别名与 autoAlpha；优先用时间线而非 delay 链式；用 addLabel() 添加标签以便阅读序列；在时间线构造函数中传入 defaults；控制播放时保存补间/时间线返回值。
十三、应避免 在变换足够时动画布局属性（width/height/top/left）；在同一 SVG 元素上同时使用 svgOrigin 与 transformOrigin；在时间线可编排时用 delay 链式；在 DOM 存在前创建补间；跳过清理——不再需要时始终 kill 补间。