HyperFrames 關鍵幀
關鍵幀是一種姿勢合約:可見狀態、連續主體身分、安全可尋的執行時間、經驗證的像素。
使用 hyperframes-animation 來處理廣泛場景配方。使用 hyperframes-cli 查閱完整命令文件。僅在選擇實作機制而非視覺風格時,才使用 references/keyframe-patterns.md。
創作者編輯邊界
關鍵幀掌管視覺運動,而非剪輯組合。來源範圍的硬切、修剪、拼接與重新排序屬於 /hyperframes-core:每個保留範圍只創作一個媒體元素,使用 data-start 和 data-duration 放置它,並以 data-media-start 選擇其來源偏移。相鄰範圍形成硬切。交叉淡化則使用不同軌道上重疊的剪輯加上視覺不透明度關鍵幀;音訊淡化則使用 /hyperframes-audio。
| 創作者請求 | 真實機制 |
|---|---|
| 推近 / 拉遠 | 在剪輯內部的非時序視覺/裁切包裝器上,對 scale 加上 x/y 或百分比平移使用關鍵幀。使用 set/short tween 處理硬推近,使用 tween 處理平滑移動。 |
| 平滑多狀態縮放或重構圖 | 保持一個主體包裝器存活,並將多個縮放/重構圖狀態創作成一組帶有逐段緩動的姿勢階梯。 |
| 平移、重構圖或 Ken Burns 攝影機移動 | 對包裝器平移加上縮放進行動畫。幾何形狀是創作出來的;這不是臉部追蹤或自動語意重構圖。 |
| 鏈式攝影機移動 | 在一個已註冊的安全可尋時間軸上,鏈接已標籤的變換節拍。 |
| 匹配剪切或揮棒平移 | /hyperframes-animation 掌管視覺交接;/hyperframes-registry 提供基本元素;關鍵幀保留創作出的幾何形狀、方向與速度。沒有自動匹配幀發現。 |
| 裁切與遮罩重構圖 | 在內部視覺包裝器上對 clip-path 或遮罩進行插值,以進行裁切/重構圖,而不改變來源時間。多邊形關鍵幀可以形成多邊形/遮罩轉場。 |
| 方向性擦拭剪輯或虹膜/揭示剪輯 | 在重疊的視覺剪輯之間對遮罩/剪裁邊界進行動畫;/hyperframes-animation 掌管交接編排。 |
| 分割畫面交接 | 保持兩個視覺剪輯由核心放置,然後對其內部裁切/遮罩包裝器與分隔線幾何形狀使用關鍵幀。 |
| 恆定來源時間重映射 | /hyperframes-core 掌管標準化的 data-playback-rate(0.1..10),以實現渲染安全的影像與音高保留的聲音。對於整個媒體元素是恆定的。 |
| 來源速度斜坡 | <video>/<audio> 上 data-automation 中的 rate 通道(t 以剪輯秒為單位,v 0.1..10,對數插值);它會覆蓋恆定速率。 |
| 凍結 / 保持 | 一個視覺姿勢、最終來源幀或完成的子合成可以保持。不支援任意中間來源凍結;請預先處理一個靜態/衍生的片段,將其作為自己的剪輯放置,然後使用另一個來源範圍繼續。 |
在同時編輯影像與聲音時,載入 /hyperframes-core、此技能用於視覺運動,以及 /hyperframes-audio 用於淡化、交叉淡化、音量自動化、閃避/雕刻,或對已放置軌道的效果。
視覺轉場或裁切處理並非時間上的來源修剪或拼接。/hyperframes-core 掌管時間軸、剪輯時序與來源範圍;關鍵幀僅對這些剪輯內部的包裝器進行視覺交接或裁切動畫。如需可複製的影音混合配方,請使用 /hyperframes-core → references/creator-editing-recipes.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() tween 使用 immediateRender: false。
關鍵幀形式
- 陣列關鍵幀:帶有逐段持續時間/緩動的姿勢階梯。
- 百分比關鍵幀:一個 tween 內部的精確時序。
- 屬性陣列:緊湊的多停止點變化。
- 當每個停止點攜帶自己的緩動時,在父級使用
ease: "none"。 - 當每個片段應共享相同感覺時,使用
easeEach。
不要從範例複製數字距離或時序。從實際的合成幾何形狀與持續時間推導出來。
對於在兩個框之間移動的一個主體,偏好一個連續的變換 tween 或 FLIP。僅在應該讓觀看者感受到不同節拍時,才將 x/y/scale 分割成多個帶有緩動的關鍵幀;每個片段都會改變速度,可能被解讀為卡頓。
通道
偏好合成器/視覺通道:x/y/z、xPercent/yPercent、scale、rotationX/Y/Z、skew、transformOrigin、svgOrigin、opacity、autoAlpha、clip-path、遮罩、CSS 變數、SVG 路徑/虛線值、攝影機變換、著色器 uniform。
避免佈局/生命週期通道:top/left/right/bottom、width/height、margin/padding、display、visibility、後期 DOM 建立、執行主體運動的輔助疊加層。
對於可見性變化,在已註冊的可尋 GSAP 時間軸上使用 autoAlpha,或在明確邊界使用零持續時間的 tl.set()。僅針對非剪輯元素或剪輯內部的包裝器;永遠不要針對 .clip 本身。永遠不要對原始 visibility 進行持續時間 tween,也永遠不要對 display 進行 tween。
機制選擇
選擇能證明提示的最簡機制:
| 需求 | 機制 |
|---|---|
| 相同主體改變盒子或層級 | 共享元素 / FLIP |
| 主體沿可見路線移動 | 路徑旅行 |
| 筆劃生長或描繪 | 筆劃繪製 |
| 一個形狀變成另一個形狀 | 形狀插值 |
| 揭示邊界是可見的 | clip、遮罩或著色器 uniform |
| 許多項目按順序移動 | 交錯 / 索引延遲 |
| 文字本身移動 | 行、詞、字元或條帶細分 |
| 表面彎曲、拉伸或裁切 | 父/子反向變換 |
| UI 有狀態 | 明確的狀態機 |
| 場景有深度 | DOM 3D、Three.js 或 WebGL 攝影機/物件關鍵幀 |
機制可以組合,但每個都必須釐清想法。裝飾不是證明。
時序
- 僅在它釐清原因或方向時才使用預期。
- 加速度離開靜止。
- 峰值證明要明確無誤地展示機制。
- 跟隨動作傳達能量與方向。
- 僅在主體應該感覺有彈性或觸感時才使用過衝。
- 恆速路徑旅行通常需要
ease: "none"。 - 離散的 UI 狀態通常需要銳利的 ease-out。
- 重複的元素需要有序的偏移,而非相同的時序。
- 最終鎖定需要比轉場姿勢更長的保持時間。
- 平滑意味著相同主體上的連續速度。
- 不要重疊寫入相同變換屬性的 tween,除非重疊是有意的且經過驗證。
- 避免在同一個主要表面正在縮放或移動時,對大型
clip-path/遮罩變化進行動畫;在主移動穩定後,使用嵌套的揭示。
文字
保留行框、字間距、可讀性與最終貼合。如果文字內部移動,移動字形或遮罩帶,而不僅僅是文字周圍的裝飾。對可讀的幀進行快照。
SVG
對於筆劃生長,偏好 DrawSVGPlugin,然後是 stroke-dasharray/stroke-dashoffset。對於形狀插值,偏好 MorphSVGPlugin;必要時將基本形狀轉換為路徑,並將複雜的輪廓分割成更簡單的部分。
3D
單獨縮放是假深度。在穩定的父級上使用透視、transform-style: preserve-3d、z 軸旅行、旋轉、攝影機/世界運動、遮擋,以及當物體交叉時的圖層順序。
使用一兩個能揭露深度關係的診斷角度。如果角度證明沒有顯示深度交叉,改進 z/攝影機/遮擋。
Canvas / WebGL
透過確定性狀態對攝影機位置、攝影機目標、物件變換、材質不透明度、著色器 uniform 與後製強度使用關鍵幀。從 HyperFrames 時間渲染。由於標記盒無法看到內部 Canvas 運動,請使用 --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 表示存在明確的停止點。motion 表示軌跡存在於多個停止點之間。ghost 顯示合成影像。overlap 表示兩個物體在同一區域。composition 表示多個物體在同一範圍內。mask 表示裁剪開孔。text 表示文字包含在內。
如果 --shot 顯示的是空白:選擇器可能錯過了目標,或者目標尚未渲染。在 --layout strip 中檢查原始佈局。如果 --ghost 看起來不像預期:Canvas 或 WebGL 可能正在讀取非確定性時間;使用 hyperframes 時間,並考慮在渲染的幀周圍加上邊界。
為軌跡使用 ghost 模式,為包含的運動使用 strip 佈局。為正式的證明使用 snapshot。如果運動在快照中看起來是正確的,即使 CLI 輸出顯示 flat,也信任視覺結果。
參考文獻
references/keyframe-patterns.md 列出動畫機制(GSAP、CSS、Anime.js、FLIP、SVG 路徑,以及 WebGL 著色器/攝影機鍵)。當意圖被理解但機制不明確時,請查閱它。不要在使用者對於他們想要哪種運動有疑問時使用它。