Communitygithub.com

GSAP 动画参考(HyperFrames)

GSAP 动画参考,专为 HyperFrames 设计。涵盖 gsap.to()、from()、fromTo()、缓动、交错、默认值、时间线(gsap.timeline()、位置参数、标签、嵌套、播放控制)以及性能优化(变换、will-change、quickTo)。在编写 HyperFrames 合成中的 GSAP 动画时使用。

GSAP 动画参考(HyperFrames) 是什么?

该技能提供了 GSAP(GreenSock 动画平台)的完整动画参考,特别面向 HyperFrames 环境。内容涵盖核心补间方法(gsap.to()、from()、fromTo()、set())、常用属性(duration、delay、ease、stagger、repeat、yoyo 等)、变换与 CSS 属性映射(如 x、y、scale、rotation、autoAlpha 等)、函数化值、内置缓动函数以及默认值设置。此外,还详细介绍了时间线(Timeline)的创建、位置参数、标签、嵌套和播放控制,以及性能最佳实践(优先使用 transform 和 opacity、will-change、gsap.quickTo() 和 stagger 优化)。技能还提供了引用文件(references/effects.md),其中包含可直接使用的特效模式,并强调了最佳实践(如使用 camelCase 属性名、优先使用时间线而非 delay 链式调用、进行清理等)和禁忌(如避免动画布局属性、避免在同一个 SVG 元素上同时使用 svgOrigin 和 transformOrigin 等)。该技能适用于 Claude Code、Cursor、Codex 等 AI 代理,能够帮助开发者高效编写符合 HyperFrames 规范的 GSAP 动画。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/govindgoel2001/video-editing-toolkit/tree/HEAD/vendor/hyperframes-skills/gsap

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

GSAP

核心补间方法

  • 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 — 数字或 -1 表示无限循环。yoyo — 与 repeat 配合使用,交替方向。
  • onComplete、onStart、onUpdate — 回调函数。
  • immediateRender — 默认 true(用于 from()/fromTo())。在后续针对相同属性和元素的补间上设置为 false,以避免覆盖。

变换与 CSS

优先使用 GSAP 的变换别名,而非原始 transform 字符串:

GSAP 属性等效 CSS 属性
x、y、ztranslateX/Y/Z(px)
xPercent、yPercenttranslateX/Y(%)
scale、scaleX、scaleYscale
rotationrotate(deg)
rotationX、rotationY3D rotate
skewX、skewYskew
transformOrigintransform-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 — 在 1s 处
  • 相对位置:"+=0.5" — 在末尾之后;"-=0.2" — 在末尾之前
  • 标签:"intro"、"intro+=0.3"
  • 对齐:"<" — 与上一个开始时间相同;">" — 在上一个结束后开始;"<0.2" — 在上一个开始后 0.2s 开始
tl.to(".a", { x: 100 }, 0);
tl.to(".b", { y: 50 }, "<"); // 与 .a 同一开始时间
tl.to(".c", { opacity: 0 }, "<0.2"); // 在 .b 开始后 0.2s 开始

标签

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()。


性能优化

优先使用 Transform 和 Opacity

动画 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 而非多个补间

使用 stagger 代替带有手动延迟的单独补间。

清理工作

暂停或终止屏幕外的动画。


参考文件(按需加载)

  • references/effects.md — 即用特效:打字机文本、音频可视化。阅读以获取可直接用于 HyperFrames 的特效模式。

最佳实践

  • 使用 camelCase 属性名;优先使用变换别名和 autoAlpha。
  • 优先使用时间线而非 delay 链式调用;使用位置参数。
  • 使用 addLabel() 添加标签,实现可读的顺序控制。
  • 将默认值传递给时间线构造函数。
  • 当需要控制播放时,保存补间/时间线的返回值。

禁止事项

  • 在变换足以满足需求时,不要动画布局属性(width/height/top/left)。
  • 不要在同一个 SVG 元素上同时使用 svgOrigin 和 transformOrigin。
  • 不要使用 delay 链式调用动画,而应使用时间线进行顺序控制。
  • 不要在 DOM 存在之前创建补间。
  • 不要跳过清理工作——当不再需要时,始终终止补间。

Individual skills in this repo

This repo contains 6 individual skills — each has its own dedicated page.

govindgoel2001/video-editing-toolkit

HyperFrames CLI tool — hyperframes init, lint, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark. Use when scaffolding a project, linting, validating, inspecting visual layout in compositions, previewing in the studio, rendering to video, transcribing audio, generating TTS, or troubleshooting the HyperFrames environment.

govindgoel2001/video-editing-toolkit

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, and registry discovery.

govindgoel2001/video-editing-toolkit

Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For CLI commands (init, lint, preview, render, transcribe, tts) see the hyperframes-cli skill.

govindgoel2001/video-editing-toolkit

Capture a website and create a HyperFrames video from it. Use when: (1) a user provides a URL and wants a video, (2) someone says "capture this site", "turn this into a video", "make a promo from my site", (3) the user wants a social ad, product tour, or any video based on an existing website, (4) the user shares a link and asks for any kind of video content. Even if the user just pastes a URL — this is the skill to use.

govindgoel2001/video-editing-toolkit

Edit any video by conversation. Transcribe, cut, color grade, generate overlay animations, burn subtitles — for talking heads, montages, tutorials, travel, interviews. No presets, no menus. Ask questions, confirm the plan, execute, iterate, persist. Production-correctness rules are hard; everything else is artistic freedom.

govindgoel2001/video-editing-toolkit

Production pipeline for mathematical and technical animations using Manim Community Edition. Creates 3Blue1Brown-style explainer videos, algorithm visualizations, equation derivations, architecture diagrams, and data stories. Use when users request: animated explanations, math animations, concept visualizations, algorithm walkthroughs, technical explainers, 3Blue1Brown style videos, or any programmatic animation with geometric/mathematical content.

相关技能