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/brief-contract.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>"](鍵 = 根的 data-composition-id)註冊恰好一個 gsap.timeline({ paused: true }),並在頁面載入時同步建立。渲染持續時間 = 根的 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注入影格,跨檔案的重複會避開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、執行時期、佈局、動態和對比度方面均無發現) - 包含子組合的專案:
npx hyperframes snapshot --at <midpoints>並目視檢查每個影格 -
npx hyperframes preview供審查(使用者可以在 Studio 的時間軸中編輯任何內容) - 僅在使用者批准後才執行
npx hyperframes render