插件安裝： 在執行 setup 或 freshness 命令之前，當此技能位於 HyperFrames 插件內部時，請遵循插件執行規則。獨立安裝則保留下方的更新說明。
HyperFrames Keyframes
關鍵影格是一種姿勢合約：可見狀態、連續的主體身份、可隨機搜尋的運行時間、以及經過驗證的像素。
使用 hyperframes-animation 來處理廣泛的場景配方。使用 hyperframes-cli 來查看完整的命令文檔。僅在選擇實現機制而非視覺風格時，才使用 references/keyframe-patterns.md。
創作者編輯邊界
關鍵影格負責視覺運動，而非剪輯組裝。原始範圍的硬切、修剪、拼接和重新排序屬於 /hyperframes-core：為每個保留的範圍創作一個媒體元素，使用 data-start 和 data-duration 放置它，並使用 data-media-start 選擇其原始偏移量。相鄰的範圍形成一個硬切。淡入淡出則使用不同軌道上重疊的剪輯加上視覺不透明度關鍵影格；音頻淡入淡出則使用 /hyperframes-audio。
| 創作者請求 | 真實機制 |
|---|---|
| 推近 / 拉遠 | 在剪輯內部的非計時視覺/裁切包裝器上，使用帶有 x/y 或百分比位移的關鍵影格 scale。使用 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 |
| 主體沿可見路徑行進 | 路徑行進 |
| 筆劃增長或追蹤 | 筆劃描繪 |
| 形狀變成另一個形狀 | 形狀插值 |
| 揭示邊界是可見的 | 剪輯、遮罩或著色器 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 時間進行渲染。使用 --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 <angle>
npx hyperframes snapshot . --at <times>
為真實的動畫主體選擇 <selector>。為第一幀、證明姿勢、最終保持前的時刻以及精確的最終幀選擇 <times>。僅在必須證明深度時選擇 <angle>。
| 工具 | 證明內容 |
|---|---|
keyframes | 目標、顯式停止點、路徑、軌跡、組合的父/子運動、CSS 停止點、Anime 註冊 |
--shot | 鬼影、路線形狀、時間間距、DOM 3D 投影、聚焦的選擇器證明 |
--layout strip | 原位運動、重疊、接觸、細微的縮放/不透明度、文字波浪 |
--ghost | canvas、WebGL、著色器運動、渲染的 3D |
snapshot --at | 遮罩、文字可讀性、完整狀態、最終鎖定、黑畫面/靜止尾部 |
如果選擇器證明看起來不對，請使用 --layout strip。如果主體佈局被遮罩裁切，請檢查快照而非 --shot。--ghost 對 canvas/WebGL 運動是必需的，因為標準的 DOM 標記無法看到它。
故障排除
- 運動未顯示：確認時間軸已註冊並暫停。使用
hyperframes keyframes . --json檢查是否有目標。 - 時序不匹配：確認
data-start、data-duration和關鍵影格時間相對於剪輯原始偏移量。 - 淡入淡出問題：區分視覺淡入淡出（用於此技能的關鍵影格）和音頻淡入淡出（用於
/hyperframes-audio）。 - 佈局跳動：從初始值和最終值開始進行 FLIP 動畫，或者對
transform和opacity使用精確的tl.fromTo()。 - 文字跳動：對文字位置使用
autoAlpha和x/y；避免關鍵影格設定width或font-size。使用帶有字元/詞條目的splitText。