Communitygithub.com

shengdabai/Tony-Claude-Code-Skills

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

Tony-Claude-Code-Skills 是什么?

此技能为在 HyperFrames 环境中使用 GSAP 编写动画提供了全面的参考指南。其核心是 HyperFrames 契约,该契约要求开发者同步创建一个暂停的时间线,并使用准确的 `data-composition-id` 将其注册到 `window.__timelines` 上,从而让 HyperFrames 能够驱动动画的进度,而不是由 GSAP 自行控制播放。技能详细介绍了 GSAP 的核心补间方法(如 `to()`、`from()`、`fromTo()` 和 `set()`),以及常用的变量配置,如持续时间、延迟、缓动函数、交错效果和重复次数。文档特别强调了在 HyperFrames 中应避免使用无限循环(`repeat: -1`),并推崇使用 `gsap.timeline()` 及其强大的位置参数来编排复杂动画序列,而不是依赖多个 `delay`。此外,还提供了性能优化建议,如优先使用变换属性(`x`、`y`、`scale`、`rotation`)而非布局属性,以及使用 `gsap.quickTo()` 处理高频更新。该技能主要面向使用 HyperFrames 的开发者,帮助他们在遵守平台规则的前提下,高效构建符合规范的 GSAP 动画。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/shengdabai/Tony-Claude-Code-Skills/tree/HEAD/skills/hyperframes-gsap

在你喜欢的 AI 中提问

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

文档

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、ztranslateX/Y/Z (px)
xPercent、yPercent百分比形式的 translateX/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。
  • 优先使用时间线而非链式 delay;使用位置参数。
  • 使用 addLabel() 添加标签以实现可读的顺序。
  • 在时间线构造函数中传入 defaults。
  • 在需要控制播放时,存储补间/时间线的返回值。

禁止事项

  • 在变换就足够的情况下,动画化布局属性(width/height/top/left)。
  • 在同一 SVG 元素上同时使用 svgOrigin 和 transformOrigin。
  • 当可以用时间线编排时,使用 delay 链式动画。
  • 在 DOM 存在之前创建补间。
  • 跳过清理 — 在不再需要时始终终止补间。
  • 在 HyperFrames 合成中使用无限重复值。始终使用根据可见时长计算的有限重复次数。

鸣谢与参考

Individual skills in this repo

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

shengdabai/Tony-Claude-Code-Skills

Downloads videos from YouTube and other platforms for offline viewing, editing, or archival. Handles various formats and quality options.

shengdabai/Tony-Claude-Code-Skills

接收抖音、小红书、微信视频号等短视频链接或分享文案,查询作品/账号数据并提取语音文字稿,按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用;运行前检查 TikHub 与轻抖使用凭证,缺少时用新手能理解的方式引导购买和安全配置。

shengdabai/Tony-Claude-Code-Skills

Read-only queue dashboard for workspace-aware ship. (gstack)

shengdabai/Tony-Claude-Code-Skills

Anime.js adapter patterns for HyperFrames. Use when writing Anime.js animations or timelines inside HyperFrames compositions, registering animations on window.__hfAnime, making Anime.js seek-driven and deterministic, or translating Anime.js examples into render-safe HyperFrames HTML.

shengdabai/Tony-Claude-Code-Skills

Author a new HyperFrames registry block (caption style, VFX block, transition, lower third) or component (text effect, overlay, snippet) and ship it as an upstream PR to the hyperframes repo. Use ONLY when the user wants to CONTRIBUTE to the public catalog — for in-project caption/transition authoring use the `hyperframes` skill, for installing existing registry items use the `hyperframes-registry` skill.

shengdabai/Tony-Claude-Code-Skills

CSS animation adapter patterns for HyperFrames. Use when authoring CSS keyframes, animation-delay based timing, animation-fill-mode, animation-play-state, or CSS-only motion that HyperFrames must seek deterministically during preview and rendering.

shengdabai/Tony-Claude-Code-Skills

HyperFrames CLI dev loop — `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the HyperFrames build/render environment. For asset preprocessing commands (`tts`, `transcribe`, `remove-background`), invoke the `hyperframes-media` skill instead.

shengdabai/Tony-Claude-Code-Skills

Asset preprocessing for HyperFrames compositions — text-to-speech narration (Kokoro), audio/video transcription (Whisper), and background removal for transparent overlays (u2net). Use when generating voiceover from text, transcribing speech for captions, removing the background from a video or image to use as a transparent overlay, choosing a TTS voice or whisper model, or chaining these (TTS → transcribe → captions). Each command downloads its own model on first run.

相关技能