HyperFrames 核心
HyperFrames 從 HTML 渲染影片。合成是一個 HTML 檔案,其 DOM 使用 data-* 屬性宣告時間,其動畫執行階段可搜尋,且媒體播放由框架擁有。
此技能是技術合約——如何建構一個 hyperframes 專案。以下內容為建構指南;每個主題的詳細資訊位於 references/(索引如下),按需閱讀。其他相關問題位於兄弟領域技能中——hyperframes-animation、hyperframes-creative、hyperframes-media、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,將片段相對於另一個片段進行時間定位 |
references/sub-compositions.md | 連接子合成(宿主屬性、<template>、每個實例的變數)並在其中製作動畫 |
references/variables-and-media.md | 宣告變數;放置 <video>/<audio>,設定音量,裁剪 |
references/determinism-rules.md | 建構可搜尋的時間軸;確定性禁止事項;可動畫屬性允許清單;佈局 / 文字適應 |
references/full-screen-motion.md | 使用共享背景創作全幀動畫 |
references/storyboard-format.md | 創作 STORYBOARD.md 計劃(+ 解析後的操作清單) |
references/script-format.md | 創作選用的 SCRIPT.md 鎖定旁白 |
references/subagent-dispatch.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>包裝(包裝它會隱藏所有內容並破壞渲染)。 - 子合成(透過
data-composition-src載入)——根必須包裹在<template>中。
⚠ 傳輸規則:執行階段僅克隆
<template>的內容;外部的一切(包括<head>樣式/腳本)都會被丟棄——請將<style>/<script>放在模板內部。 ⚠ 宿主 ID 規則:宿主槽的data-composition-id必須完全等於內部模板的data-composition-id以及window.__timelines["<id>"]的鍵——不要使用-mount/-slot/-host後綴。
檔案形狀、宿主連接以及預渲染檢查清單 → references/sub-compositions.md。
根必須有尺寸(靜默佈局錯誤)
獨立的根需要一個明確的尺寸盒子(以 px 為單位的 width/height),並且直達 height:100% 元素的每個祖先都必須有解析的高度——否則 flex/100% 的子元素會收縮到約 0,內容會堆疊到左上角。lint/validate/inspect 不會捕捉到這一點。骨架 → references/minimal-composition.md。
一個暫停的時間軸
每個合成在 window.__timelines["<id>"] 註冊恰好一個 gsap.timeline({ paused: true })(鍵 = 根 data-composition-id),在頁面載入時同步建構。渲染持續時間 = 根 data-duration,而非時間軸長度。不要手動將子時間軸嵌套到宿主中。完整合約(包括非 GSAP 執行階段)→ references/determinism-rules.md + hyperframes-animation/adapters/。
不可協商的規則(lint/validate/inspect 不會捕捉到的靜默錯誤)
在此列出;完整理由請參閱連結的參考文件。請勿違反:
- 不得使用執行時時脈 / 未種子的
Math.random/ 網路 / 輸入狀態;不得使用repeat: -1(請使用有限次數)。→determinism-rules.md - 僅在視覺屬性允許清單上製作動畫;永遠不要使用
display/visibility;不要在後續場景的片段上使用gsap.set。→determinism-rules.md - 正文中不得使用
<br>;轉換後的元素必須是區塊級別且已設定尺寸;脈衝式的絕對定位裝飾元素需要頂部間距。→determinism-rules.md <video>/<audio>必須是宿主根元素的直接子元素(永遠不要在子合成<template>/包裝器內部);框架擁有播放控制權。→variables-and-media.md- 每個
id在組裝後的頁面中必須是唯一的;在子合成內部,請使用合成 ID 作為 id 的前綴(#<id>-hero)。重複的<video>/<img>id 會渲染為空白——生成器透過getElementById注入幀,而跨檔案的重複 ID 會從lint中溜走。→composition-patterns.md - 全螢幕場景的填充應放在一個滿版出血的子元素上(
position:absolute; inset:0),永遠不要放在合成根元素本身上——生成器的幀合成可能會丟棄根元素自身的background(幀會渲染為黑色),即使預覽/snapshot顯示正常。→composition-patterns.md
編輯現有合成
- 先閱讀檔案。保留不相關的時間、軌道、ID、變數、媒體路徑。
- 匹配現有的合成 ID 和時間軸鍵。
- 新增片段:選擇一個非重疊的
data-track-index或有意地調整周圍的時間。 - 新增子合成:在連接宿主之前,驗證其內部的
data-composition-id。
驗證
使用 hyperframes-cli 取得命令詳細資訊
-
npx hyperframes lint通過(0 個錯誤) -
npx hyperframes validate通過(0 個控制台錯誤) -
npx hyperframes inspect通過(0 個錯誤) - 包含子合成的專案:
npx hyperframes snapshot --at <midpoints>並目視檢查每一幀 -
npx hyperframes preview用於檢閱(使用者可以在 Studio 的時間軸中編輯任何內容) - 僅在使用者批准後才執行
npx hyperframes render