HyperFrames Core
HyperFrames 從 HTML 渲染影片。組合(composition)是一個 HTML 檔案,其 DOM 使用 data-* 屬性宣告時間,動畫運行時是可回溯的,且媒體播放由框架所擁有。
此技能是技術合約。其他關注點位於同級技能中:
hyperframes-animation— 原子運動規則 + 場景藍圖 + 各運行時適配器(GSAP、Lottie、Three、Anime.js、CSS、WAAPI、TypeGPU)hyperframes-creative— 調色盤、字體排印、旁白、節奏規劃、音訊反應hyperframes-media— TTS、Whisper 轉錄、背景去除、字幕hyperframes-registry— 安裝區塊與組件(hyperframes add)hyperframes-cli— 開發迴圈命令(lint / validate / preview / render)
對於 Tailwind v4 專案(hyperframes init --tailwind),請參閱 references/tailwind.md — 瀏覽器運行時合約與 Studio 的 Tailwind v3 設定不同。
路由
| 想要做什麼… | 請閱讀 |
|---|---|
| 查看最小可渲染組合 | references/minimal-composition.md |
| 決定使用單一檔案還是模組化子組合架構 | references/composition-patterns.md |
結構化模組化 index.html(編排器 + 插槽 + 根音訊) | references/composition-patterns.md |
| 選擇子組合原型(內容 / 僅驅動 / 多場景合併 / 音訊反應) | references/composition-patterns.md |
查詢 data-* 屬性(根元素、片段、子組合主機、舊別名) | references/data-attributes.md |
正確使用 class="clip" | references/data-attributes.md |
選擇 data-track-index;相同軌道重疊;軌道索引 vs CSS z-index | references/tracks-and-clips.md |
使片段相對於另一個片段計時(data-start="intro + 2"、交叉淡入重疊、鏈) | references/tracks-and-clips.md |
連接子組合(主機屬性、<template> 包裝器、每個實例變數) | references/sub-compositions.md |
在子組合內動畫(gsap.fromTo 優於 gsap.from、回溯行為) | references/sub-compositions.md |
宣告變數(類型、額外選項、預設值、CI 中的 --strict-variables) | references/variables-and-media.md |
放置 <video> / <audio>、設定音量、使用 data-media-start 修剪 | references/variables-and-media.md |
建立可回溯時間軸(暫停、同步建構、gsap.set 後期場景陷阱) | references/determinism-rules.md |
避免非確定性狀態(時鐘、Math.random、repeat: -1、有限重複公式) | references/determinism-rules.md |
了解哪些可以/不可以動畫(視覺屬性允許清單;不是 display/visibility) | references/determinism-rules.md |
適應文字並防止溢出(fitTextFontSize 簽名、<br> 規則、佈局合約) | references/determinism-rules.md |
| 創作帶有共享背景的全幀動畫 | references/full-screen-motion.md |
在 Tailwind v4 專案中工作(init --tailwind) | references/tailwind.md |
如需動畫運行時細節(GSAP API、Lottie、Three.js 等),請前往 hyperframes-animation → adapters/<runtime>.md。
組合物結構
兩種根形式;它們不可互換。
- 獨立式(頂層
index.html)— 根元素<div data-composition-id="…">直接位於<body>中。無<template>包裝器。 將獨立根元素包裹在<template>中會對瀏覽器隱藏所有內容並破壞渲染。 - 子組合(透過
data-composition-src載入的檔案)— 根元素<div data-composition-id="…">必須包裹在<template>中。若無包裝器,運行時無法提取並掛載它。
⚠ 子組合傳輸規則:運行時僅將
<template>內容克隆到即時 DOM 中。模板外的所有內容——包括<head>以及位於<head>中的任何<style>/<script>/<link>——都會被丟棄。將<style>和<script>區塊放在<template>內部,而不是<head>中。⚠ 主機 ID 規則:在主機檔案中,插槽上的
data-composition-id必須完全等於內部模板的data-composition-id以及window.__timelines["<id>"]的鍵。請勿添加-mount/-slot/-host後綴。
有關檔案形狀、主機接線、陷阱示例以及預渲染驗證檢查清單,請參閱 references/sub-compositions.md。
根元素必須設定大小(隱形佈局錯誤)
獨立根元素必須建立一個明確設定大小的盒子,並且根元素與 height: 100% 元素之間的每個祖先都必須有已解析的高度。如果根元素或中間包裝器沒有高度,則 flex/height:100% 內容容器會收縮到 ~0,內容堆疊到左上角(通常在第一個字元 x=0 處被裁剪)。lint、validate 和 inspect 不會捕捉到這一點——inspect 會用作者設定的 data-width/data-height 替換已收縮的根元素,並報告「0 個佈局問題」。
<body style="margin: 0">
<div
id="root"
data-composition-id="main"
data-width="1920"
data-height="1080"
data-duration="5"
style="position: relative; width: 1920px; height: 1080px; overflow: hidden"
>
<!-- 穩健置中:position:absolute + inset:0 填滿已設定大小的根元素,無論中間包裝器為何;
或者僅在父鏈已設定大小時使用 flex 容器。 -->
<section
class="clip"
data-start="0"
data-duration="5"
data-track-index="1"
style="position: absolute; inset: 0; display: grid; place-items: center; padding: 120px 160px; box-sizing: border-box"
>
<h1>標題</h1>
</section>
</div>
</body>
將 padding(≥80px)保留在置中容器上——這是標題安全邊距,可防止大字型碰到框架邊緣。請參閱 references/minimal-composition.md。
時間軸合約(GSAP 預設)
每個組合物恰好註冊一個 GSAP 時間軸。
- 使用
gsap.timeline({ paused: true })建立 — 播放器擁有播放控制權。 - 註冊於
window.__timelines["<composition-id>"];該鍵必須完全匹配根元素的data-composition-id。當 id 是有效的標識符時,點語法(window.__timelines.<id> = tl)是等效的;如果 id 包含-,請使用方括號。 - 在頁面載入期間同步建立時間軸 — 不要在
async、setTimeout、Promise或事件處理常式內部。渲染器在頁面載入完成後進行取樣;任何延遲的時間軸建構都會錯過取樣。 - 渲染時長來自根元素上的
data-duration,而非 GSAP 時間軸長度。請勿用空的補間填充時間軸來設定時長。 - 對於子組合,不要手動將子時間軸巢狀嵌套到主機中(
master.add(sub));框架會獨立驅動它們。
對於非 GSAP 運行時(Lottie / Three / WAAPI / CSS / Anime.js / TypeGPU),等效合約位於 hyperframes-animation/adapters/<runtime>.md。請參閱 references/determinism-rules.md 以了解跨運行時的動畫運行時合約。
不可協商的規則
這些規則會破壞渲染器——或產生 lint/validate/inspect 無法捕捉的隱形視覺錯誤(規則 3、7-8)。(同步時間軸建構已在時間軸合約中介紹。)
- 不使用
Math.random()/Date.now()/performance.now()驅動視覺效果 — 使用種子化 PRNG。 - 不使用
repeat: -1。使用repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1)— 使用floor,而非ceil(ceil會超出data-duration並觸發gsap_repeat_ceil_overshootlint 警告;max(0, …)可避免負數重複 = 無限重複)。 <video>/<audio>必須是主機根元素(index.html)的直接子元素 — 絕不能在子組合<template>內部,也絕不能在包裝器<div>內部;否則永遠不會被解碼並渲染為空白/黑色(隱形)。框架擁有播放控制權:不使用video.play()/audio.play()/currentTime = …。子組合無法驅動主機元素(選擇器或querySelector),因此請在主時間軸上以全域時間對主機媒體進行動畫處理。請參閱references/variables-and-media.md。- 不要對後期場景的片段元素使用
gsap.set()(它們尚不在 DOM 中)。請在或晚於片段的data-start時間點使用tl.set(selector, vars, time)。 - 不要對
display/visibility進行動畫處理。對opacity/ 變換進行動畫處理;片段生命週期負責顯示/隱藏。 - 正文中不使用
<br>。讓文字透過max-width自動換行。 - 轉換的元素必須是區塊級並設定大小。
transform/scaleX/scaleY對內聯<span>無效,且縮放一個自動寬度(0px)的元素不會顯示任何內容 → 不可見的條/填充。為它們設定display: block/inline-block/flex-item 以及實際的width/height(例如在已設定大小的父元素內使用width: 100%)。 - 絕對定位的裝飾元素(徽章、藥丸形狀、標籤)如果跳動或過衝(
yoyo縮放、back.out),需要在峰值大小時留出空隙,且不得跨越overflow: hidden邊緣——否則它們會與相鄰元素重疊或被裁剪。定位應針對最大幀,而非靜止幀。
編輯現有組合物
- 在編輯前實際閱讀檔案。
- 保留不相關的時間、軌道、ID、變數和媒體路徑。
- 匹配現有的組合物 ID 和時間軸註冊表鍵。
- 添加片段時,選擇不重疊的
data-track-index,或有意調整周圍的時間。 - 添加子組合時,在連接主機前驗證其內部的
data-composition-id。
驗證
使用 hyperframes-cli 獲取命令細節。
-
npx hyperframes lint通過(0 錯誤) -
npx hyperframes validate通過(0 控制台錯誤) -
npx hyperframes inspect通過,或已明確標記溢出 - 具有子組合的專案:
npx hyperframes snapshot --at <midpoints>並目視檢查每個畫面