Communitygithub.com

shengdabai/Tony-Claude-Code-Skills

用於 HyperFrames 的 GSAP 動畫參考。涵蓋 gsap.to()、from()、fromTo()、easing、stagger、defaults、時間軸(gsap.timeline()、位置參數、標籤、巢狀結構、播放控制)以及效能(transform、will-change、quickTo)。適用於在 HyperFrames 組合中編寫 GSAP 動畫。

Tony-Claude-Code-Skills 是什麼?

此技能提供在 HyperFrames 環境中編寫高效 GSAP 動畫的完整參考指南。它重點說明 HyperFrames 所需的特定合約:必須同步建立暫停的 GSAP 時間軸,並將其註冊到 `window.__timelines` 物件中,使用與組合根元素 `data-composition-id` 完全匹配的鍵值。技能詳細介紹了核心補間方法(to、from、fromTo、set)、常見變數(duration、ease、stagger、repeat)、支援的 CSS 轉換屬性別名,以及如 `autoAlpha` 和方向性旋轉等進階功能。此外,它還深入探討了時間軸的建立與控制,包括位置參數、標籤和巢狀結構,同時提供提升渲染效能的建議,例如優先使用 transform 和 opacity 動畫、善用 `gsap.quickTo()` 處理頻繁更新,以及使用 stagger 取代大量獨立補間。技能也明確列出了在 HyperFrames 中應避免的操作,例如使用無限重複值或非同步建立時間軸。

相容平台✓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。請同步建立一個暫停的時間軸,將其註冊到 window.__timelines,並使用準確的 data-composition-id,接著讓 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; // 鍵值必須與組合根元素的 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 別名,而非原始 transform 字串:

GSAP 屬性等效 CSS 屬性
x、y、ztranslateX/Y/Z (px)
xPercent、yPercenttranslateX/Y 百分比
scale、scaleX、scaleYscale
rotationrotate (deg)
rotationX、rotationY3D 旋轉
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()。


效能

偏好使用 Transform 與 Opacity

對 x、y、scale、rotation、opacity 進行動畫處理時,會停留在合成器層級。如果 transform 能達到相同效果,請避免使用 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 屬性名稱;偏好 transform 別名與 autoAlpha。
  • 偏好使用時間軸而非以 delay 串連動畫;使用位置參數。
  • 使用 addLabel() 加入標籤以實現可讀性高的排序。
  • 將預設值傳入時間軸建構函式。
  • 當需要控制播放時,儲存補間/時間軸的回傳值。

禁止事項

  • 當 transform 能夠達到相同效果時,不要對版面屬性(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.

相關技能