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 | 將子代理分派動詞(並行擴散 / 背景 / 等待)對應到您的 harness |
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>放在 template 內部。 ⚠ 宿主 ID 規則:宿主插槽的data-composition-id必須完全等於內部 template 的data-composition-id以及window.__timelines["<id>"]鍵 — 不能有-mount/-slot/-host後綴。
檔案形狀、宿主連接以及預渲染檢查清單 → references/sub-compositions.md。
根必須設定大小(無聲的佈局錯誤)
獨立根需要一個明確的有尺寸的盒子(width/height 以 px 為單位),且每個向上直到 height:100% 元素的祖先都必須有解析的高度 — 否則 flex/100% 的子元素會崩潰到約 0,內容堆積在左上角。lint/validate/inspect 不會捕捉到此問題。骨架 → references/minimal-composition.md。
一個暫停的時間軸
每個組合註冊恰好一個 gsap.timeline({ paused: true }) 於 window.__timelines["<id>"](鍵 = 根 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在組裝後的頁面中必須是唯一的;在子組合內部,為 IDs 加上組合 ID 前綴(#<id>-hero)。重複的<video>/<img>IDs 會呈現空白 — 生產者透過getElementById注入幀,跨檔案重複會繞過lint。 →composition-patterns.md - 全螢幕場景填充應放在一個滿版出血的子元素上(
position:absolute; inset:0),永遠不要放在組合根本身 — 生產者的幀合成可能會丟棄根元素自己的background(該幀會渲染成黑色),即使預覽/snapshot顯示正確。 →composition-patterns.md
編輯現有組合
- 先閱讀檔案。保留不相關的時間、軌道、IDs、變數、媒體路徑。
- 匹配現有組合 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僅在使用者批准後執行