HyperFrames 關鍵幀
關鍵幀是一種姿勢合約:可視狀態、連續的主體身份、可安全查找的執行時間、經過驗證的像素。
使用 hyperframes-animation 處理寬泛場景配方。
使用 hyperframes-cli 查閱完整命令文檔。
僅在選擇實現機制(而非視覺風格)時,才使用 references/keyframe-patterns.md。
程序
- 識別動畫主體、可視狀態、最終狀態及執行時間。
- 選擇能夠證明提示的最小機制。僅在機制不明確時才閱讀
references/keyframe-patterns.md。 - 在宣告的執行時間內撰寫可安全查找的關鍵幀。同步建構並註冊執行時間實例。
- 使用 lint、validate、
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 建立、用於主體動作的輔助疊加層。
機制選擇
選擇能夠證明提示的最小機制:
| 需求 | 機制 |
|---|---|
| 相同主體改變方框或層級結構 | 共享元素 / FLIP |
| 主體沿可視路徑移動 | 路徑行進 |
| 筆畫增長或追蹤 | 筆畫繪製 |
| 一個形狀變成另一個形狀 | 形狀插值 |
| 揭露邊界可視 | 剪裁、遮罩或著色器統一變量 |
| 許多項目按順序移動 | 錯開 / 索引延遲 |
| 文字本身移動 | 行、單詞、字元或帶狀細分 |
| 表面彎曲、拉伸或裁剪 | 父/子反向變換 |
| UI 具有狀態 | 顯式狀態機 |
| 場景具有深度 | DOM 3D、Three.js 或 WebGL 相機/物件關鍵幀 |
機制可以組合,但每一種都必須闡明想法。裝飾不是證明。
時間掌握
- 僅在能闡明原因或方向時使用預期動作。
- 加速離開靜止狀態。
- 峰值證明應明確無誤地展示機制。
- 後續動作體現能量和方向。
- 僅在主體應感覺有彈性或有觸感時使用超調。
- 恆速路徑行進通常需要
ease: "none"。 - 離散的 UI 狀態通常需要銳利的 ease-out。
- 重複元素需要有序偏移,而非相同時間。
- 最終鎖定需要比過渡姿勢更長的保持時間。
- 平滑意味著同一主體上速度連續。
- 除非故意重疊且經過驗證,否則不要重疊寫入相同變換屬性的補間。
- 避免在主要英雄表面同時縮放或移動時動畫化大型
clip-path/遮罩變化;應在主要移動穩定後使用嵌套揭露。
文字
保留行框、單詞間距、可讀性和最終佈局。如果文字在內部移動,則移動字形或遮罩帶,而不僅是文字周圍的裝飾。對可讀幀進行快照。
SVG
對於筆畫增長,偏好使用 DrawSVGPlugin,然後是 stroke-dasharray/stroke-dashoffset。
對於形狀插值,偏好使用 MorphSVGPlugin;必要時將基本形狀轉換為路徑,並將複雜輪廓拆分為更簡單的部分。
3D
僅有縮放是假的深度。
在穩定的父級上使用透視、transform-style: preserve-3d、z 軸移動、旋轉、相機/世界運動、遮擋以及物件交叉時的圖層順序。
使用一到兩個能揭示深度關係的診斷角度。若有角度的證明未顯示深度交叉,則改進 z/相機/遮擋。
Canvas / WebGL
透過確定性狀態設定關鍵幀:相機位置、相機目標、物件變換、材質透明度、著色器統一變量和後處理強度。從 HyperFrames 時間渲染。使用 --ghost,因為標記框無法看到內部 Canvas 運動。
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 <角度>
npx hyperframes snapshot . --at <時間點>
為實際的動畫主體選擇 <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/相機移動、遮擋、有角度證明 |
| 錯誤的最終 | 添加最終保持,快照最終保持前一刻和精確最終幀 |
| 不可查找的執行時間 | 暫停自動播放,註冊實例,移除計時器,同步建構 |
| 不可讀的文字 | 保留行框,減少位移,添加最終保持,對文字幀進行快照 |
完成
執行 lint、validate、keyframes、一個聚焦的 --shot 和快照。確認第一幀、證明姿勢、最終保持前一刻、精確最終幀、主體擁有的運動,且沒有除錯疊加層。