外掛安裝: 在執行 setup 或 freshness 指令前,當此技能位於 HyperFrames 外掛中時,請遵循外掛執行規則。獨立安裝則保留下方更新說明。
HyperFrames 核心
代理陷阱(優先閱讀):
- 使用 flex/
inset置中,不要在後續 GSAPx/y動畫的節點上使用 CSStransform: translate(-50%,-50%)。Lint 檢查:gsap_css_transform_conflict。請使用fromTo或xPercent/yPercent。 - 不要添加場景退出的
tl.set(..., {visibility:"hidden"})。運行時已隱藏計時的剪輯。在內部節點(或.clip上的opacity)上進行不透明度淡出就已足夠。字幕強制終止是另一套規則。 window.__timelines["id"]必須與根元素的data-composition-id匹配。- 在
render之後,讀取摘要的第二行:beginframevsscreenshot、GPU 模式、階段時間。Linux 上的screenshot+software gpu是慢速路徑。
HyperFrames 從 HTML 渲染影片。合成是一個 HTML 檔案,其 DOM 使用 data-* 屬性宣告時間,其動畫運行時是可搜尋的,且其媒體播放由框架擁有。
此技能是技術合約 — 如何建構一個 hyperframes 專案。以下內容為建構指南;每個主題的詳細資料位於 references/(索引見下),按需閱讀。流程文件(簡報、分鏡、審查、製作、調度、影格工作者)位於 /hyperframes → references/。其他關注點位於相關領域技能 — hyperframes-animation、hyperframes-creative、media-use、hyperframes-cli、hyperframes-registry。位於 /hyperframes 的能力對應圖說明了每個技能涵蓋的範圍。
參考資料
| 檔案 | 閱讀時機… |
|---|---|
references/minimal-composition.md | 從最小的可渲染合成骨架開始 |
references/composition-patterns.md | 選擇整體式 vs 模組化;結構化模組化 index.html;選擇子合成原型 |
references/data-attributes.md | 查詢任何 data-*(根元素/剪輯/子合成宿主/舊別名);使用 class="clip" |
references/tracks-and-clips.md | 了解 data-track-index 控制(與不控制)什麼、z-index、相對於另一個剪輯的時間;使用 npx hyperframes timeline 列出每個時間軌與剪輯 |
references/creator-editing-recipes.md | 複製正確的剪下/修剪/重新排序/重新計時/凍結/相機/遮罩/交叉淡出/音訊編輯食譜及其限制 |
references/sub-compositions.md | 連接子合成(宿主屬性、<template>、每個實例變數)並在其中製作動畫 |
references/variables-and-media.md | 宣告變數;放置 <video>/<audio>、設定音量、修剪 |
references/determinism-rules.md | 建構可搜尋時間軸;確定性禁令;版面配置/文字適配 |
references/full-screen-motion.md | 使用共享背景製作全螢幕動畫 |
references/tailwind.md | 在 Tailwind v4 專案中工作(init --tailwind;運行時合約與 Studio 的 v3 不同) |
如需動畫運行時細節(GSAP API、Lottie、Three.js 等),請參閱 hyperframes-animation → adapters/<runtime>.md。
建構合成
兩種根形式(不可互換)
- 獨立式(頂層
index.html):根元素<div data-composition-id="…">直接位於<body>中,沒有<template>包裝。包裝獨立式根元素會隱藏所有內容,並且lint會拒絕它(standalone_composition_wrapped_in_template,錯誤)。 - 子合成(透過
data-composition-src載入):將根元素包裹在<template>中。這是建議撰寫的形式:載入器也接受純完整的文件並回退到其<body>,但範例和工具預期的是模板化形式。
⚠ 傳輸規則:對於模板化的子合成,組裝器會丟棄檔案自身的
<head><style>/<script>(位於packages/core/src/compiler/compositionAssembly.ts,hasTemplate閘門),因此請將<style>/<script>放在模板內部。<link>無論如何都會被提升。 ⚠ 宿主 ID 慣例:給予宿主插槽、內部模板以及window.__timelines["<id>"]鍵相同的 ID。也支援不同的本地 ID(組裝器會回退到檔案中的第一個根元素),但這種不匹配是靜默的,因此除非有理由,否則請保持它們一致。
檔案結構、宿主連接以及預渲染檢查清單 → references/sub-compositions.md。
根元素必須設定大小(靜默版面配置錯誤)
獨立式根元素需使用 width/height: 100%。畫布大小由 data-width/data-height 決定。運行時會將這些像素值應用到合成根元素上。不要在 #root 上硬編碼 1920px/1080px。骨架 → references/minimal-composition.md。
一個暫停的時間軸
每個合成註冊恰好一個 gsap.timeline({ paused: true }) 到 window.__timelines["<id>"](鍵值 = 根元素 data-composition-id)。在非同步回呼(document.fonts.ready)內部建構它是被支援的;重要的是你只有在建構完成後才註冊。渲染長度是根元素的 data-duration,不是時間軸的長度:超過它的時間軸部分會被截斷,而提前結束的時間軸會保持其最後一幀。省略根元素的 data-duration 則會改為推斷長度(時間軸、媒體視窗或適配器)。你不需要 window.__timelines = window.__timelines || {}:運行時會在你的內嵌腳本執行前創建註冊表,並且 lint 不再要求它。不要手動將子時間軸巢狀到宿主中;運行時會自動巢狀已註冊的子時間軸。完整合約(包含非 GSAP 運行時)→ references/determinism-rules.md + hyperframes-animation/adapters/。
首次 lint 陷阱(保證首次建構失敗)
lint 會捕捉的規則,但僅在事後。第一次就寫對它們:
- 永遠不要將 CSS 初始
transform與 GSAP 在相同屬性上的補間動畫配對 — CSS 值與補間的起始值會衝突,且lint會以gsap_css_transform_conflict拒絕它。請使用gsap.fromTo(el, { x: -40 }, { x: 0 })在補間內部設定初始狀態,而不是使用 CSStransform: translateX(-40px)。 - 永遠不要在
<video>/<audio>上放置crossorigin。lint會無條件以media_crossorigin_breaks_preview(錯誤)拒絕它,包含用於 canvas/WebGL/WebAudio 回讀的情況。沒有抑制方法。 - 永遠不要給一個帶
data-start的<video>一個也帶有data-start的祖先。lint會以video_nested_in_timed_element(錯誤)拒絕它。計時要嘛在包裝元素上,要嘛在影片上,不能兩者皆有。 - 每個
<audio>都需要一個id。lint會以media_missing_id拒絕它,而且沒有 ID 的<audio>永遠不會被混音器拾取,因此渲染會是靜音的。 - 永遠不要使用
autoAlpha或visibility補間.clip—lint會以gsap_animates_clip_element拒絕它。請改為動畫其子元素。 - 命名的 CSS
font-family需要一個檔案內的@font-face指向已交付的本地檔案,否則lint會觸發font_family_without_font_face。 - 子合成
#root使用width/height: 100%(或inset: 0),而不是硬編碼的1920px/1080px。畫布大小是data-width/data-height。
lint 錯誤也會關閉版面配置和對比度稽核:check 隨後會報告 0 sample(s) 和 0/0 text checks,這看起來像是乾淨的檔案,但實際上什麼都沒執行。在信任這些數字之前,請先清除 lint 錯誤。
不可協商的規則(自動化閘門可能遺漏的靜默錯誤)
在此列出;完整理由請參閱連結的參考資料。請勿違反:
- 沒有渲染時時鐘 / 未播種的
Math.random/ 網路 / 輸入狀態;repeat: -1只能在有限的根元素data-duration下使用(匯出剪輯到它 — 否則使用有限次數)。→determinism-rules.md - 永遠不要在
.clip元素上補間display、visibility或autoAlpha。框架擁有剪輯的可見性,且lint會拒絕它(gsap_animates_clip_element)。請改為動畫其子元素。→determinism-rules.md - 主文中沒有
<br>;被轉換的元素必須是區塊級且已設定大小;脈動的絕對定位裝飾元素需要峰值間距。→determinism-rules.md <video>/<audio>透過平面文件查詢找到,因此框架可以在任何巢狀深度(包含在子合成<template>或包裝元素內部)搜尋和解碼它們。一個硬性限制:如果一個<video data-start>位於另一個也帶有data-start的普通元素內部,lint會報錯,且這個失敗是真實的(錯誤的來源影格,然後剪輯在中間時段消失),所以要嘛在包裝元素上,要嘛在影片上設定時間,永遠不要兩者皆有。子合成宿主是例外:子合成內部的媒體會正確渲染。另一個注意事項是時間軸,而不是放置位置:子合成時間軸不能動畫宿主根元素。→variables-and-media.md- 在組裝後的頁面上保持每個
id唯一(為子合成 ID 加上合成 ID 前綴,例如#<id>-hero),以便你自己的#idCSS 和getElementById呼叫能正確解析。影格注入不再依賴於此:編譯器會為每個video[src]/audio[src]/img[src]蓋上文件唯一的data-hf-render-id。使用<source>子元素而非src屬性的媒體不會被蓋上此標記,因此唯一 ID 在那裡仍然重要。→composition-patterns.md - 在合成根元素上的全螢幕填滿在正常渲染時是可行的。它只會在分層合成路徑上被丟棄(HDR 內容,或使用著色器轉場的合成),在該路徑下引擎會強制每個合成根元素透明,以便底層能夠顯現。如果你的合成使用著色器轉場或 HDR 媒體,請將填滿放在一個全出血的子元素上(
position:absolute; inset:0)。→composition-patterns.md
編輯現有合成
- 先讀取檔案。保留不相關的時間、時間軌、ID、變數、媒體路徑。
- 要了解專案時間軸上的內容(時間軌、剪輯、開始、結束、播放的內容),請執行
npx hyperframes timeline [--json],而不是讀取index.html和每個子合成檔案。 - 匹配現有的合成 ID 和時間軸鍵值。
- 添加剪輯:有意識地針對周圍的剪輯設定其
data-start/data-duration。data-track-index是 Studio 顯示通道,不是時間限制,因此它不需要是空閒的。 - 在根元素
data-duration之後結束的剪輯會被截斷:在同一編輯中將根元素data-duration延伸到剪輯的結束時間(lint會警告clip_ends_past_root_duration)。 - 任何合成元素上的
data-hidden會在預覽和渲染中隱藏它,覆蓋其時間視窗;它是非破壞性/可逆的,並由 Studio 的時間軸眼睛圖標切換。 - 添加子合成:在連接宿主之前驗證其內部的
data-composition-id。
驗證
使用 hyperframes-cli 獲取命令詳細資料
-
npx hyperframes check通過(在 lint、運行時、版面配置、動畫和對比度中皆為 0 個發現) - 包含子合成的專案:
npx hyperframes snapshot --at <midpoints>並目視檢查每個影格 -
npx hyperframes preview --background用於審查(用戶可以在 Studio 時間軸中編輯任何內容,且伺服器在調用命令後繼續運行) - 僅在用戶批准後執行
npx hyperframes render