GSAP
HyperFrames 契约
HyperFrames 通过其 gsap 运行时适配器控制 GSAP。同步创建一个暂停的时间线,使用确切的 data-composition-id 将其注册到 window.__timelines 上,让 HyperFrames 驱动其进度。
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
tl.from(".title", { y: 48, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.to(".accent", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.25);
window.__timelines["main"] = tl; // key 必须等于合成根元素的 data-composition-id
</script>
- 注册表键必须匹配合成根元素的
data-composition-id。 - 不要为渲染关键的运动调用
tl.play()。 - 不要在异步代码、计时器或事件处理程序内构建时间线。
- 保持循环有限。HyperFrames 渲染有限的视频时长。
核心补间方法
- gsap.to(targets, vars) — 从当前状态动画到
vars。最常用。 - gsap.from(targets, vars) — 从
vars动画到当前状态(入场)。 - gsap.fromTo(targets, fromVars, toVars) — 明确的起始和结束状态。
- gsap.set(targets, vars) — 立即应用(持续时间为 0)。
始终使用 小驼峰 (camelCase) 属性名称(例如 backgroundColor、rotationX)。
常用变量
- 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 — 有限数值;在 HyperFrames 中永远不要使用
-1。根据可见时长计算重复次数。yoyo — 与 repeat 配合,交替方向。 - onComplete、onStart、onUpdate — 回调函数。
- immediateRender — 对于 from()/fromTo() 默认为
true。如果后续补间针对同一属性和元素,则设置为false以避免覆盖。
变换与 CSS
优先使用 GSAP 的 变换别名 而非原生的 transform 字符串:
| GSAP 属性 | 等价属性 |
|---|---|
x、y、z | translateX/Y/Z (px) |
xPercent、yPercent | 百分比形式的 translateX/Y |
scale、scaleX、scaleY | scale |
rotation | rotate (度) |
rotationX、rotationY | 3D rotate |
skewX、skewY | skew |
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"。
基于函数的值
gsap.to(".item", {
x: (i, target, targets) => i * 50,
stagger: 0.1,
});
缓动
内置缓动:power1–power4、back、bounce、circ、elastic、expo、sine。每个都有 .in、.out、.inOut 变体。
默认值
gsap.defaults({ duration: 0.6, ease: "power2.out" });
控制补间
const tween = gsap.to(".box", { x: 100 });
tween.pause();
tween.play();
tween.reverse();
tween.kill();
tween.progress(0.5);
tween.time(0.2);
gsap.matchMedia() (响应式与无障碍)
仅在媒体查询匹配时运行设置;不匹配时自动恢复。
let mm = gsap.matchMedia();
mm.add(
{
isDesktop: "(min-width: 800px)",
reduceMotion: "(prefers-reduced-motion: reduce)",
},
(context) => {
const { isDesktop, reduceMotion } = context.conditions;
gsap.to(".box", {
rotation: isDesktop ? 360 : 180,
duration: reduceMotion ? 0 : 2,
});
},
);
时间线
创建时间线
const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });
位置参数
第三个参数控制放置位置:
- 绝对时间:
1— 在 1 秒处 - 相对时间:
"+=0.5"— 在结尾之后;"-=0.2"— 在结尾之前 - 标签:
"intro"、"intro+=0.3" - 对齐:
"<"— 与上一个开始时间相同;">"— 在上一个结束后开始;"<0.2"— 在上一个开始后 0.2 秒
tl.to(".a", { x: 100 }, 0);
tl.to(".b", { y: 50 }, "<"); // 与 .a 同一时间开始
tl.to(".c", { opacity: 0 }, "<0.2"); // 在 .b 开始后 0.2 秒
标签
tl.addLabel("intro", 0);
tl.to(".a", { x: 100 }, "intro");
tl.addLabel("outro", "+=0.5");
tl.play("outro");
tl.tweenFromTo("intro", "outro");
时间线选项
- paused: true — 创建时暂停;调用
.play()开始。 - repeat、yoyo — 应用于整个时间线。
- defaults — 合并到每个子补间的变量。
嵌套时间线
const master = gsap.timeline();
const child = gsap.timeline();
child.to(".a", { x: 100 }).to(".b", { y: 50 });
master.add(child, 0);
播放控制
tl.play()、tl.pause()、tl.reverse()、tl.restart()、tl.time(2)、tl.progress(0.5)、tl.kill()。
性能
优先使用变换和透明度
动画 x、y、scale、rotation、opacity 保持在合成器上。当变换可以达到相同效果时,避免使用 width、height、top、left。
will-change
will-change: transform;
仅用于实际产生动画的元素。
用于频繁更新的 gsap.quickTo()
let xTo = gsap.quickTo("#id", "x", { duration: 0.4, ease: "power3" }),
yTo = gsap.quickTo("#id", "y", { duration: 0.4, ease: "power3" });
container.addEventListener("mousemove", (e) => {
xTo(e.pageX);
yTo(e.pageY);
});
使用交错而非多个补间
使用 stagger 代替多个带手动延迟的补间。
清理
暂停或终止屏幕外的动画。
参考资料(按需加载)
- references/effects.md — 即用型效果:打字机文字、音频可视化器。在需要为 HyperFrames 提供现成的效果模式时阅读。
最佳实践
- 使用小驼峰属性名称;优先使用变换别名和 autoAlpha。
- 优先使用时间线而非链式 delay;使用位置参数。
- 使用
addLabel()添加标签以实现可读的顺序。 - 在时间线构造函数中传入 defaults。
- 在需要控制播放时,存储补间/时间线的返回值。
禁止事项
- 在变换就足够的情况下,动画化布局属性(width/height/top/left)。
- 在同一 SVG 元素上同时使用 svgOrigin 和 transformOrigin。
- 当可以用时间线编排时,使用 delay 链式动画。
- 在 DOM 存在之前创建补间。
- 跳过清理 — 在不再需要时始终终止补间。
- 在 HyperFrames 合成中使用无限重复值。始终使用根据可见时长计算的有限重复次数。
鸣谢与参考
- HyperFrames 适配器源码:
packages/core/src/runtime/adapters/gsap.ts。 - GSAP 文档:https://gsap.com/docs/v3/
- GSAP 时间线暂停和 seek 行为:https://gsap.com/docs/v3/GSAP/Timeline/pause%28%29/