HyperFrames 核心
HyperFrames 從 HTML 渲染影片。一個組合是一個 HTML 檔案,其 DOM 使用 data-* 屬性宣告時序,其動畫執行環境是可搜尋的,且媒體播放由框架擁有。
此技能是技術合約 — 如何建立一個 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;使一個片段相對於另一個片段定位時間 |
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/review-loop.md | 在動態看板上執行計畫 → 草稿 → 建構審查循環 — 由每個分鏡規劃工作流程共享 |
references/production-loop.md | 將已批准的計畫轉變為交付的影片 — 階段依賴關係(音訊、影格、組裝、轉場、字幕、驗證、交付)一個自由形式的建構直接跟隨 |
references/brief-contract.md | 簡報的基本規則 — 模式推導(協作/自主)、共享欄位註冊表、問題不變量(提問本身位於 /hyperframes → 意圖層) |
references/brief-format.md | 撰寫 BRIEF.md — 工作流程的 Setup 撰寫且每個後續步驟都讀取的已確認意圖文件 |
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>放在模板內部。 ⚠ 宿主 ID 規則:宿主插槽的data-composition-id必須完全等於內部模板的data-composition-id以及window.__timelines["<id>"]鍵 — 無-mount/-slot/-host後綴。
檔案形狀、宿主連接及預渲染檢查清單 → references/sub-compositions.md。
根必須設定大小(無聲佈局錯誤)
獨立式根需要一個明確的定尺寸盒子(width/height 以 px 為單位),並且向下到 height:100% 元素的每個祖先都必須有解析的高度 — 否則 flex/100% 子元素會收縮到約 0,內容會堆疊到左上角。不要僅依賴自動化閘門來捕獲此問題;檢查快照。骨架 → references/minimal-composition.md。
一個暫停的時間軸
每個組合在 window.__timelines["<id>"](鍵 = 根 data-composition-id)註冊恰好一個 gsap.timeline({ paused: true }),在頁面載入時同步建構。渲染持續時間 = 根 data-duration,而不是時間軸長度。不要手動將子時間軸嵌套到宿主中。完整合約(包括非 GSAP 執行時期)→ references/determinism-rules.md + hyperframes-animation/adapters/。
不可協商的規則(自動化閘門可能遺漏的無聲錯誤)
在此列出;完整理由在連結的參考文件中。請勿違反:
- 無執行時期時鐘/未播種的
Math.random/網路/輸入狀態;無repeat: -1(使用有限計數)。 →determinism-rules.md - 僅對視覺屬性允許清單進行動畫處理;切勿調整
display或原始visibility。GSAPautoAlpha和零持續時間時間軸邊界設定是唯一的可見性例外,並且僅能對非片段元素或片段內的包裝器使用。框架獨自控制.clip可見性。不要在頁面載入時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注入影格,跨檔案的重複內容會繞過lint。 →composition-patterns.md - 全螢幕場景填充應放在一個滿版的子元素(
position:absolute; inset:0)上,永遠不要在組合根元素本身 — 製作者的影格合成可能會丟棄根元素自身的background(影格渲染為黑色),即使預覽/snapshot顯示正確。 →composition-patterns.md
編輯現有組合
- 先閱讀檔案。保留不相關的時序、軌道、ID、變數、媒體路徑。
- 匹配現有的組合 ID 和時間軸鍵。
- 新增片段:選擇一個非重疊的
data-track-index或有意地調整周圍時序。 data-hidden在任何組合元素上會隱藏它在預覽和渲染中的顯示,覆蓋其時間視窗;它是非破壞性/可逆的,並由 Studio 的時間軸眼睛圖示切換。- 新增子組合:在連接宿主之前驗證其內部的
data-composition-id。
驗證
使用 hyperframes-cli 以獲取命令詳細資訊
-
npx hyperframes check通過(在 lint、執行時期、版面、動態和對比度方面發現 0 個問題) - 具有子組合的專案:
npx hyperframes snapshot --at <midpoints>並檢查每個影格 - 用於審查的
npx hyperframes preview(用戶可以在 Studio 的時間軸中編輯任何內容) - 僅在用戶批准後才使用
npx hyperframes render