插件安裝: 在執行設定或更新命令之前,若此技能位於 HyperFrames 插件內部,請遵循插件執行規則。獨立安裝則保留下方更新說明。
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。 - 在宣告的執行時間內創作可搜尋安全的關鍵幀。僅在建置完成後註冊執行時間實例;在
document.fonts.ready內部進行建置是可以的。 - 使用
hyperframes check(執行 lint)、hyperframes keyframes、一個專注的--shot以及在證明時間點的快照進行驗證。 - 如果證明失敗,修正來源關鍵幀,並在渲染前重新執行最小的失敗診斷。
合約
- 為移動的主體命名。
- 列出證明預期動作所需的姿態,包括最終狀態。
- 對可見通道進行關鍵幀設定,而非隱藏的輔助狀態。
- 當連續性重要時,保持物件身份。
- 僅當預期動作是取代或溶解時,才使用交叉淡入淡出。
- 將可讀或語義狀態保持足夠長的時間以便觀察。
- 最終幀是動畫的一部分,並非清理動作。
- 除非要求,否則不要重置到靜止狀態。
- 除非要求,否則不要以黑色結束。
- 如果編輯起始場景,除非要求重新設計,否則保留佈局、文案、資源、顏色和最終狀態。
執行時間規則
GSAP:
- 在頁面載入時或
document.fonts.ready內部進行建置,且僅在建置完成後註冊 - 使用
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
單純的縮放是虛假的景深。在穩定的父級上使用 perspective、transform-style: preserve-3d、z 軸移動、旋轉、攝影機/世界運動、遮擋以及物件交叉時的圖層順序。
使用一個或兩個能揭露深度關係的診斷角度。如果角度證明未顯示深度交叉,改進 z/攝影機/遮擋。
Canvas / WebGL
透過確定性狀態對攝影機位置、攝影機目標、物件變換、材質不透明度、著色器 Uniform 和後處理強度進行關鍵幀設定。從 HyperFrames 時間渲染。使用 --ghost,因為標記方塊無法看到內部 Canvas 運動。
CLI 證明
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 | 遮罩 |
…
[因翻譯而被截斷]