外掛安裝: 在執行設定或刷新命令前,若此技能位於 HyperFrames 外掛內部,請遵循外掛執行規則。獨立安裝則保留下方的更新說明。
HyperFrames 關鍵影格
關鍵影格是一種姿勢合約:可見狀態、連續主體身分、安全可尋的執行時、經驗證的像素。
使用 hyperframes-animation 處理廣泛場景配方。使用 hyperframes-cli 取得完整命令文件。僅在選擇實作機制而非視覺風格時,才使用 references/keyframe-patterns.md。
創作者編輯邊界
關鍵影格負責視覺運動,而非片段組裝。來源範圍的硬切、修剪、拼接和重排屬於 /hyperframes-core:為每個保留範圍創作一個媒體元素,使用 data-start 和 data-duration 放置,並使用 data-media-start 選擇其來源偏移。相鄰範圍構成硬切。淡入淡出使用重疊的片段位於不同軌道加上視覺不透明度關鍵影格;聲音淡入淡出使用 /hyperframes-audio。
| 創作者請求 | 真實機制 |
|---|---|
| 推入 / 推出 | 對片段內的非計時視覺/裁剪包裝器,關鍵影格化 scale 搭配 x/y 或百分比平移。使用設定的短補間進行硬推,使用補間進行平滑移動。 |
| 平滑多狀態縮放或重新構圖 | 保留一個主體包裝器存活,並將多個縮放/重新構圖狀態創作爲一個姿勢階梯,每個段落各有自己的緩動。 |
| 平移、重新構圖或 Ken Burns 攝影機運動 | 動畫化包裝器平移加上縮放。幾何形狀是創作而成;這不是臉部追蹤或自動語義重新構圖。 |
| 鏈式攝影機運動 | 在一個已註冊的安全可尋時間軸上,鏈接標記的變換節拍。 |
| 匹配剪輯或揮動平移 | /hyperframes-animation 擁有視覺傳遞;/hyperframes-registry 提供基本元素;關鍵影格保留創作的幾何形狀、方向和速度。沒有自動匹配影格發現。 |
| 裁剪和遮罩重新構圖 | 在內部視覺包裝器上插值 clip-path 或遮罩,以裁剪/重新構圖而不改變來源時間。多邊形關鍵影格可以形成多邊形/遮罩轉場。 |
| 方向性擦拭剪輯或虹膜/揭露剪輯 | 跨重疊的視覺片段動畫化遮罩/剪輯邊界;/hyperframes-animation 擁有傳遞編排。 |
| 分割畫面傳遞 | 保留核心放置的兩個視覺片段,然後關鍵影格化它們的內部裁剪/遮罩包裝器和分隔線幾何形狀。 |
| 恆定來源重新計時 | /hyperframes-core 擁有標準化的 data-playback-rate (0.1..10),用於渲染安全的圖像和音高保留的聲音。它對整個媒體元素是恆定的。 |
| 來源速度斜坡 | data-automation 中的 rate 通道作用於 <video>/<audio>(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() 補間,使用 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 狀態通常需要銳利的 ease-out。
- 重複元素需要有序偏移,而非相同時序。
- 最終鎖定需要比過渡姿勢更長的保持。
- 平滑意味著在同一主體上的連續速度。
- 除非重疊是故意的並經驗證,否則不要重疊寫入相同變換屬性的補間。
- 避免在相同的主體表面也在縮放或移動時,動畫化大型
clip-path/遮罩更改;在主運動穩定後使用巢狀揭露。
文字
保留行框、字詞間距、可讀性和最終佈局。如果文字在內部移動,移動字形或遮罩頻帶,而不僅僅是文字周圍的裝飾。對可讀影格進行快照。
SVG
對於筆觸生長,優先使用 DrawSVGPlugin,然後是 stroke-dasharray/stroke-dashoffset。對於形狀插值,優先使用 MorphSVGPlugin;必要時將基本圖形轉換為路徑,並將複雜輪廓拆分為更簡單的部分。
3D
單獨的縮放是假的深度。在穩定的父級上使用透視、transform-style: preserve-3d、z 移動、旋轉、攝影機/世界運動、遮擋以及物件交叉時的圖層順序。
使用一個或兩個能揭露深度關係的診斷角度。如果帶角度的證明顯示沒有深度交叉,改進 z/攝影機/遮擋。
Canvas / WebGL
通過確定性狀態,對攝影機位置、攝影機目標、物件變換、材質不透明度、著色器統一變數和後處理強度進行關鍵影格化。從 HyperFrames 時間渲染。使用 --ghost,因為標記框無法看到內部畫布運動。
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 | 畫布、WebGL、著色器運動、渲染的 3D |
snapshot --at | 遮罩、剪輯邊界、最終鎖定、文字行對齊、觸控/地面接觸 |
診斷
點狀飾必須與主體一起移動。如果它們沒有移動,則為點狀飾使用單獨的 tl.to()。
對於複合形狀,證明輪廓在經過轉換時與自身重疊。對於路徑,證明點數曲線保持了橫向位置。
當探索性的 debug 參數被找到但不在 skill/SKILL.md 中時,將預設行為記錄到 debug/。
模板快取
npx hyperframes keyframes . --store-template <name>
使用命名的關鍵影格範本,使常見模式可從多個合成中引用。
安裝: npm install hyperframes-keyframes
更新: npm update hyperframes-keyframes
入門: 參閱 references/getting-started.md。
配方: 參閱 recipes/。
合約: 參閱 CONTRACT.md。
參考:
references/keyframe-patterns.md— 機制選擇references/gsap-recipes.md— GSAP 範例references/css-keyframes-recipes.md— CSS 範例resources/animejs-cheatsheet.md— Anime.js 參考resources/waapi-cheatsheet.md— WAAPI 參考bibliography/— 背景文章changelog/— 版本歷史