Communitygithub.com

nateherkai/hyperframes-student-kit

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

hyperframes-student-kit 是什么?

这是一个专为 HyperFrames 学生开发者设计的 GSAP 动画技能参考文件。它系统地整理了 GSAP 的核心特性和最佳实践,包括基础补间方法(to、from、fromTo、set)、常用变量(持续时间、延迟、缓动、交错、重复、回调)、CSS 变换别名和性能优化策略。文档还深入介绍了时间线的创建、位置参数控制、标签使用、嵌套以及播放控制方法,并提供了 matchMedia、quickTo 等高级功能的示例。该技能支持所有使用 GSAP 的 HyperFrames 项目,尤其适合需要创建复杂动画序列的开发场景。它的价值在于将分散的 GSAP API 知识浓缩为一个结构化参考,帮助开发者避免常见错误(如使用布局属性而非变换、链式延迟而非时间线),并遵循 HyperFrames 的最佳实践。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nateherkai/hyperframes-student-kit/tree/HEAD/.agents/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)。

始终使用 驼峰式 属性名(例如 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 — 与重复配合使用,交替方向。
  • onComplete、onStart、onUpdate — 回调函数。
  • immediateRender — 对于 from()/fromTo() 默认为 true。对于后续针对同一属性和元素的补间动画,设置为 false 以避免覆盖。

变换和 CSS

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

GSAP 属性等价属性
x、y、ztranslateX/Y/Z (px)
xPercent、yPercenttranslateX/Y(百分比)
scale、scaleX、scaleYscale
rotationrotate(度)
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 — 在 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。
  • 优先使用时间线而非链式延迟;使用位置参数。
  • 使用 addLabel() 添加标签以实现可读的序列编排。
  • 在时间线构造函数中传递默认值。
  • 在需要控制播放时存储补间动画/时间线的返回值。

禁忌

  • 避免在变换可以实现相同效果时动画化布局属性(width/height/top/left)。
  • 避免在同一个 SVG 元素上同时使用 svgOrigin 和 transformOrigin。
  • 避免在时间线可以编排序列时使用延迟来链式动画。
  • 避免在 DOM 存在之前创建补间动画。
  • 不要跳过资源清理——始终在不再需要时终止补间动画。

Individual skills in this repo

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

nateherkai/hyperframes-student-kit

Agent 2 of the video editing pipeline. Finds and removes spoken mistakes — stutters, repeated words, false starts, and retakes (re-recorded lines) — from a talking-head recording. Use after cut-silences, when asked to cut mistakes, remove stutters / repeats / filler restarts, clean up flubs, or keep the best take. Works review-gated: it proposes every cut with context and a reason for approval, then renders only the approved cuts via ffmpeg. Requires a word-level transcript.

nateherkai/hyperframes-student-kit

Agent 1 of the video editing pipeline. Removes silences and dead air from a talking-head recording. Use when asked to cut silences, trim pauses, remove dead air / gaps, or tighten the pacing of a raw video, given a word-level transcript. Produces an edit list (EDL), a re-timed transcript for downstream agents, and optionally the cut video via ffmpeg. Does NOT cut mistakes, repeats, or false starts — that is the cut-mistakes agent.

nateherkai/hyperframes-student-kit

Edit a raw talking-head video through transcription, silence trimming, mistake review, visual storytelling, motion graphics, and verified HyperFrames rendering. Use for a complete edit; route a single requested operation directly to its specialist skill.

nateherkai/hyperframes-student-kit

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

nateherkai/hyperframes-student-kit

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.

nateherkai/hyperframes-student-kit

Plan, write, time, style, and validate motion-graphic beats for long-form talking-head HyperFrames videos. Use when Codex is asked to add or improve visual beats, glassmorphism lower thirds, crumpled-paper full-screen takeovers, transcript-synced callouts, pacing coverage, YouTube retention graphics, or render-ready overlays in an existing HyperFrames video project.

nateherkai/motion-showreel

Build 10–30s motion-design showreels in the style of Nate's Opus 5.5 CLAUDE/MOTION REEL — brand motif chapters, HUD, BPM-locked cuts, logo lockup.

nateherkai/website-to-hyperframes

Capture a website URL and produce a HyperFrames promo/product-tour video — site → finished marketing video outcome.

相关技能