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之後,閱讀摘要的第二行:beginframe與screenshot、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 回讀。沒有任何抑制方法。 - 永遠不要給一個
<video data-start>加上一個也帶有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(使用有限計數)。→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-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