HyperFrames 關鍵幀
關鍵幀是一種姿勢合約:可見狀態、連續主體身份、可安全尋址的執行環境、經過驗證的像素。
對於廣泛場景配方,請使用 hyperframes-animation。
對於完整命令文件,請使用 hyperframes-cli。
僅在選擇實作機制而非視覺風格時,才使用 references/keyframe-patterns.md。
流程
- 識別動畫主體、可見狀態、最終狀態與執行時間。
- 選擇能證明提示的最小機制。僅在機制不明確時才閱讀
references/keyframe-patterns.md。 - 在宣告的執行時間中,編寫可安全尋址的關鍵幀。同步建置並註冊執行時間實例。
- 使用
hyperframes lint、hyperframes check、hyperframes keyframes、一個聚焦的--shot以及證明時間點的快照進行驗證。 - 若證明失敗,請修正原始關鍵幀,並在渲染前重新執行最小的失敗診斷。
合約
- 為移動主體命名。
- 命名證明預期動作所需的姿勢,包括最終狀態。
- 對可見通道設定關鍵幀,而非隱藏的輔助狀態。
- 在需要連續性時保持物件身份。
- 僅在預期動作為替換或淡出淡入時才進行交叉淡變。
- 讓可讀取或語意狀態持續足夠長的時間。
- 最終影格是動畫的一部分,非清理用途。
- 除非被要求,否則不要重置回靜止狀態。
- 除非被要求,否則不要以黑色畫面結束。
- 若正在編輯起始場景,除非被要求重新設計,否則請保留版面配置、文案、素材、顏色與最終狀態。
執行時間規則
GSAP:
- 在頁面載入時同步建置
- 使用
gsap.timeline({ paused: true }) - 註冊為
window.__timelines[compositionId] - 註冊鍵必須與
data-composition-id匹配 - 切勿為渲染關鍵的動作呼叫
tl.play() - 保持重複次數有限
CSS 關鍵幀:
- 有限的持續時間與疊代次數
- 確定的延遲
animation-fill-mode: both- 當時間屬於某個剪輯時使用
data-start
Anime.js:
- 同步建立
autoplay: false- 有限的持續時間與循環次數
- 將每個實例推入
window.__hfAnime
WAAPI:
- 有限的
duration fill: "both"- 確定的建構方式
- 文字表面不列出 WAAPI;請使用
--shot(它會尋址 WAAPI)與快照進行驗證
切勿用於渲染關鍵的動作:
Date.now()performance.now()- 未設定種子的
Math.random() - 懸停/滾動觸發器
- 計時器
- 非同步建立的時間軸
- 未註冊的
requestAnimationFrame - 無限循環
GSAP 骨架
const root = document.querySelector("[data-composition-id]");
const compositionId = root.dataset.compositionId;
const tl = gsap.timeline({ paused: true });
tl.addLabel("state-a", 0);
tl.to(".subject", {
keyframes: [
{ x: 0, opacity: 1, duration: 0.2 },
{ x: 120, opacity: 1, duration: 0.4, ease: "power2.out" },
{ x: 100, opacity: 1, duration: 0.2, ease: "power2.inOut" },
],
ease: "none",
});
window.__timelines = window.__timelines || {};
window.__timelines[compositionId] = tl;
使用標籤表示語意狀態。使用位置參數而非鏈接延遲。對觸及相同屬性的後續 from()/fromTo() 補間使用 immediateRender: false。
關鍵幀形式
- 陣列關鍵幀:帶有逐步驟持續時間/緩動的姿勢階梯。
- 百分比關鍵幀:單個補間內的精確時間。
- 屬性陣列:緊湊的多站點變更。
- 當每個站點自帶緩動時,父級使用
ease: "none"。 - 當每個片段應共享相同感覺時使用
easeEach。
請勿從範例中複製數值距離或時間。根據實際構圖的幾何形狀與持續時間推導它們。
對於在兩個盒子之間移動的單一主體,偏好一個連續的變換補間或 FLIP。僅在希望觀看者感受到不同節拍時,才將 x/y/scale 拆分為多個帶緩動的關鍵幀;每個片段都會改變速度,可能被視為卡頓。
通道
偏好合成器/視覺通道:x/y/z、xPercent/yPercent、scale、rotationX/Y/Z、skew、transformOrigin、svgOrigin、opacity、autoAlpha、clip-path、遮罩、CSS 變數、SVG 路徑/虛線值、攝影機變換、著色器統一變數。
避免佈局/生命週期通道:top/left/right/bottom、width/height、margin/padding、display、visibility、後期 DOM 建立、執行主體動作的輔助疊加層。
對於可見性變更,在已註冊的可尋址 GSAP 時間軸上使用 autoAlpha,或在明確邊界處使用零持續時間的 tl.set()。僅針對非剪輯元素的元素或剪輯內的包裝器;切勿針對 .clip 本身。切勿對原始 visibility 進行持續時間補間,也切勿對 display 進行補間。
機制選擇
選擇能證明提示的最小機制:
| 需求 | 機制 |
|---|---|
| 相同主體改變盒子或層級結構 | 共享元素 / FLIP |
| 主體沿可見路線移動 | 路徑移動 |
| 筆畫生長或描繪 | 筆畫繪製 |
| 形狀變為另一種形狀 | 形狀插值 |
| 揭示邊界可見 | 剪輯、遮罩或著色器統一變數 |
| 多個項目按順序移動 | 交錯 / 索引延遲 |
| 文字本身移動 | 行、詞、字元或帶狀細分 |
| 表面彎曲、拉伸或裁剪 | 父/子反向變換 |
| UI 具有狀態 | 明確狀態機 |
| 場景具有深度 | DOM 3D、Three.js 或 WebGL 攝影機/物件關鍵幀 |
機制可以組合,但每個機制都必須澄清概念。裝飾不是證明。
時間
- 僅在能澄清原因或方向時使用預期動作。
- 加速離開靜止。
- 峰值證明應明確顯示機制。
- 跟隨動作傳達能量與方向。
- 僅在主體應感覺有彈性或觸感時使用過衝。
- 恆定速度的路徑移動通常需要
ease: "none"。 - 離散的 UI 狀態通常需要銳利的減速緩動。
- 重複元素需要有序偏移,而非相同時間。
- 最終鎖定需要比過渡姿勢更長的保持時間。
- 流暢意味著同一主體上的連續速度。
- 除非有意且經驗證,否則不要重疊寫入相同變換屬性的補間。
- 避免在主要英雄表面同時縮放或移動時,動畫化大型
clip-path/遮罩變更;請在主移動穩定後使用巢狀揭示。
文字
保留行盒子、詞間距、可讀性與最終適配。若文字內部移動,請移動字型或遮罩帶,而不僅是文字周圍的裝飾。快照可讀取的影格。
SVG
對於筆畫生長,優先使用 DrawSVGPlugin,然後使用 stroke-dasharray/stroke-dashoffset。對於形狀插值,優先使用 MorphSVGPlugin;必要時將基本圖形轉換為路徑,並將複雜輪廓拆分為更簡單的部分。
3D
單獨的縮放是虛假的深度。在穩定的父級上使用透視、transform-style: preserve-3d、z 軸移動、旋轉、攝影機/世界運動、遮擋以及物件交叉時的圖層順序。
使用一個或兩個能揭露深度關係的診斷角度。若角度證明未顯示深度交叉,請改進 z/攝影機/遮擋。
Canvas / WebGL
透過確定性狀態設定關鍵幀:攝影機位置、攝影機目標、物件變換、材質不透明度、著色器統一變數以及後處理強度。從 HyperFrames 時間進行渲染。使用 --ghost,因為標記框無法看到內部畫布運動。
CLI 證明
npx hyperframes lint
npx hyperframes check
npx hyperframes keyframes .
npx hyperframes keyframes . --json
npx hyperframes keyframes . --runtime all
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --samples <n>
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --layout strip --from <t0> --to <t1>
npx hyperframes keyframes . --shot "<file>" --ghost --angle <angle>
npx hyperframes snapshot . --at <times>
為真實動畫主體選擇 <selector>。為第一影格、證明姿勢、最終保持前以及精確最終狀態選擇 <times>。僅在需要證明深度時選擇 <angle>。
| 工具 | 證明 |
|---|---|
keyframes | 目標、明確停止點、路徑、軌跡、組合的父/子運動、CSS 停止點、Anime 註冊 |
--shot | 鬼影、路線形狀、時間間距、DOM 3D 投影、聚焦選擇器證明 |
--layout strip | 就地運動、重疊、接觸、微妙的縮放/不透明度、文字波浪 |
--ghost | Canvas、WebGL、著色器運動、渲染的 3D |
snapshot --at | 遮罩、文字可讀性、完整狀態、最終鎖定、黑色/重置尾端 |
若選擇器證明看起來有誤:
- 重新執行
--json - 找到實際的動畫目標
- 拍攝該目標
- 快照完整影格
- 信任已繪製的像素而非日誌
診斷解讀
flat 表示沒有明確的中間姿勢。keyframes 表示存在明確的停止點。motionPath 表示存在路線。trace 表示多筆畫繪製。composed with 表示子級運動繼承了父級運動。
均勻的鬼影間距表示恆定速度。聚集的鬼影表示慢入或穩定。大間距表示快速移動。
輔助選擇器拍攝並非證明。在破碎的完整影格上進行洋蔥皮拍攝並非證明。
錯誤處理
| 失敗 | 修復 |
|---|---|
| 僅有端點 | 添加中間姿勢、保持峰值證明、重新執行 --shot |
| 身份斷裂 | 保持一個元素存活、使用共享來源/最終盒子、移除替代交叉淡變 |
| 偽 3D | 添加 z/攝影機移動、遮擋、角度證明 |
| 錯誤的最終狀態 | 添加最終保持、快照最終保持前與精確最終狀態 |
| 無法尋址的執行環境 | 暫停自動播放、註冊實例、移除計時器、同步建構 |
| 無法閱讀的文字 | 保留行盒子、減少位移、添加最終保持、快照文字影格 |
完成
執行 hyperframes lint、hyperframes check、hyperframes keyframes、一個聚焦的 --shot 以及快照。確認第一影格、證明姿勢、最終保持前、精確最終狀態、主體擁有的運動,且沒有除錯疊加層。