HyperFrames
HTML 是影片的真實來源。一個合成就是一個 HTML 檔案,帶有 data-* 屬性來控制時間、一個 GSAP 時間軸來控制動畫,以及 CSS 來控制外觀。這個框架負責處理片段的可見性、媒體播放和時間軸同步。
方法
在撰寫 HTML 之前,先從高層次思考:
- 什麼 — 觀眾應該體驗到什麼?辨識出敘事弧線、關鍵時刻和情感節奏。
- 結構 — 需要多少個合成?哪些是子合成,哪些是內聯的?哪些音軌承載哪些內容(影片、音訊、疊加層、字幕)?
- 時間 — 哪些片段驅動時長?轉場發生在何處?節奏如何?
- 佈局 — 先建構最終狀態。請參閱下方的「先佈局後動畫」。
- 動畫 — 然後根據以下規則加入動態。
對於小規模修改(調整顏色、調整時間、加入一個元素),可以直接跳到規則部分。
視覺識別閘門
按此順序檢查:
- 專案中是否存在 DESIGN.md? → 讀取它。使用其中確切的顏色、字型、動態規則和「不要做的事項」限制。
- 是否存在 visual-style.md? → 讀取它。應用其中的
style_prompt_full和結構化欄位。(注意:visual-style.md是專案專用檔案。visual-styles.md是包含 8 個命名預設的樣式庫 — 不同的檔案。) - 使用者指定了樣式(例如「瑞士脈衝」、「暗黑科技風」、「奢華品牌」)? → 讀取 visual-styles.md 中的 8 個命名預設。產出一個簡潔的 DESIGN.md,包含:
## Style Prompt(一個段落)、## Colors(3-5 個帶角色的十六進位色值)、## Typography(1-2 個字型系列)、## What NOT to Do(3-5 個反模式)。 - 以上皆非? → 在撰寫任何 HTML 前,先問 3 個問題:
- 情緒是什麼?(爆炸性 / 電影感 / 流暢 / 技術感 / 混亂 / 溫暖)
- 淺色還是深色畫布?
- 有任何特定的品牌色、字型或視覺參考嗎? 然後根據回答產出一個簡潔的 DESIGN.md。
每個合成都必須將其調色板和字型追溯到 DESIGN.md、visual-style.md 或明確的使用者指示。如果你正在使用 #333、#3b82f6 或 Roboto — 你跳過了這個步驟。
關於動態預設值、尺寸、入場模式和緩動函數 — 請遵循 house-style.md。house style 處理如何移動。DESIGN.md 處理事物看起來像什麼。
先佈局後動畫
將每個元素定位在它最顯眼的時刻應該在的位置 — 也就是它完全進入、正確放置、且尚未退出的影格。先將其寫成靜態的 HTML+CSS。此時不要使用 GSAP。
為何重要: 如果你將元素定位在它們的動畫起始狀態(畫面外、縮放至 0、透明度 0),然後將其補間到你認為它們應該落地的位置,你就是在猜測最終佈局。重疊在影片渲染之前是看不見的。透過先建構最終狀態,你可以在加入任何動態之前,先看到並修正佈局問題。
流程
- 識別每個場景的英雄影格 — 也就是最多元素同時可見的時刻。這就是你要建構的佈局。
- 為該影格撰寫靜態 CSS。
.scene-content容器必須使用width: 100%; height: 100%; padding: Npx;並搭配display: flex; flex-direction: column; gap: Npx; box-sizing: border-box來填滿整個場景。使用 padding 將內容向內推 — 絕對不要在內容容器上使用position: absolute; top: Npx。絕對定位的內容容器在內容高於剩餘空間時會溢出。position: absolute僅保留給裝飾性元素使用。 - 使用
gsap.from()加入入場動畫 — 從畫面外/不可見動畫至 CSS 位置。CSS 位置是真實狀態;補間描述的是到達那裡的過程。 - 使用
gsap.to()加入離場動畫 — 從 CSS 位置動畫至畫面外/不可見。
範例
/* scene-content 填滿場景,padding 定位內容 */
.scene-content {
display: flex;
flex-direction: column;
justify-content: center;
width: 100%;
height: 100%;
padding: 120px 160px;
gap: 24px;
box-sizing: border-box;
}
.title {
font-size: 120px;
}
.subtitle {
font-size: 42px;
}
/* 容器填滿任何場景尺寸 (1920x1080, 1080x1920, 等等)。
Padding 定位內容。Flex + gap 處理間距。 */
錯誤示範 — 硬編碼尺寸和絕對定位:
.scene-content {
position: absolute;
top: 200px;
left: 160px;
width: 1920px;
height: 1080px;
display: flex; /* ... */
}
// 步驟 3:動畫進入這些位置
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);
// 步驟 4:從這些位置動畫離開
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);
當元素跨時間共享空間時
如果元素 A 在元素 B 進入同一區域之前退出,兩者都應在其各自的英雄影格中具有正確的 CSS 位置。時間軸順序保證它們永遠不會在視覺上共存 — 但如果你跳過了佈局步驟,你就不會發現它們因時間錯誤而意外重疊的情況。
什麼算是有意重疊
分層效果(文字後方的光暈、陰影元素、背景圖案)和 z 軸堆疊設計(卡片堆疊、深度圖層)是故意的。佈局步驟的目的是為了捕捉非預期的重疊 — 兩個標題疊在一起、一個統計數字蓋住標籤、內容溢出影格邊界。
資料屬性
所有片段
| 屬性 | 必要 | 值 |
|---|---|---|
id | 是 | 唯一識別符 |
data-start | 是 | 秒數或片段 ID 參考 ("el-1", "intro + 2") |
data-duration | img/div/合成需要 | 秒數。影片/音訊預設為媒體時長。 |
data-track-index | 是 | 整數。相同音軌的片段不能重疊。 |
data-media-start | 否 | 來源的剪裁偏移量(秒數) |
data-volume | 否 | 0-1(預設為 1) |
data-track-index 不影響視覺分層 — 請使用 CSS z-index。
合成片段
| 屬性 | 必要 | 值 |
|---|---|---|
data-composition-id | 是 | 唯一的合成 ID |
data-start | 是 | 開始時間(根合成:使用 "0") |
data-duration | 是 | 優先於 GSAP 時間軸時長 |
data-width / data-height | 是 | 像素尺寸(1920x1080 或 1080x1920) |
data-composition-src | 否 | 外部 HTML 檔案路徑 |
合成結構
透過 data-composition-src 載入的子合成使用 <template> 包裝。獨立合成(主要的 index.html)不使用 <template> — 它們將 data-composition-id 的 div 直接放在 <body> 中。在獨立檔案上使用 <template> 會將所有內容隱藏於瀏覽器,從而破壞渲染。
子合成結構:
<template id="my-comp-template">
<div data-composition-id="my-comp" data-width="1920" data-height="1080">
<!-- content -->
<style>
[data-composition-id="my-comp"] {
/* scoped styles */
}
</style>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
// tweens...
window.__timelines["my-comp"] = tl;
</script>
</div>
</template>
在根目錄載入:<div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>
影片和音訊
影片必須是 muted playsinline。音訊始終為獨立的 <audio> 元素:
<video
id="el-v"
data-start="0"
data-duration="30"
data-track-index="0"
src="video.mp4"
muted
playsinline
></video>
<audio
id="el-a"
data-start="0"
data-duration="30"
data-track-index="2"
src="video.mp4"
data-volume="1"
></audio>
時間軸合約
- 所有時間軸都以
{ paused: true }開始 — 播放器控制播放 - 註冊每個時間軸:
window.__timelines["<composition-id>"] = tl - 框架會自動巢狀化子時間軸 — 請不要手動加入它們
- 時長來自
data-duration,而不是來自 GSAP 時間軸長度 - 永遠不要建立空的補間來設定時長
規則(不可協商)
確定性: 不使用 Math.random()、Date.now() 或基於時間的邏輯。如果需要擬隨機值,請使用種子 PRNG(例如 mulberry32)。
GSAP: 僅動畫視覺屬性(opacity、x、y、scale、rotation、color、backgroundColor、borderRadius、變形)。不要動畫 visibility、display 或呼叫 video.play()/audio.play()。
動畫衝突: 永遠不要同時從多個時間軸對同一元素的同一屬性進行動畫。
不要使用 repeat: -1: 無限重複的時間軸會破壞擷取引擎。請根據合成時長計算確切的重複次數:repeat: Math.ceil(duration / cycleDuration) - 1。
同步時間軸建構: 永遠不要在 async/await、setTimeout 或 Promise 內部建構時間軸。擷取引擎會在頁面載入後同步讀取 window.__timelines。字型由編譯器內嵌,因此立即可用 — 無需等待字型載入。
絕對不要做:
- 忘記註冊
window.__timelines - 使用影片的音訊 — 始終使用靜音影片 + 獨立的
<audio> - 將影片巢狀在計時 div 內部 — 使用非計時的包裝器
- 使用
data-layer(使用data-track-index)或data-end(使用data-duration) - 動畫影片元素的尺寸 — 動畫一個包裝 div
- 呼叫媒體的 play/pause/seek — 框架擁有播放控制權
- 建立沒有
data-composition-id的頂層容器 - 在任何時間軸或補間上使用
repeat: -1— 始終使用有限重複 - 非同步建構時間軸(在
async、setTimeout、Promise內部) - 對來自後續場景的片段元素使用
gsap.set()— 它們在頁面載入時不存在於 DOM 中。請改用時間軸內部在或超過片段data-start時間的tl.set(selector, vars, timePosition)。 - 在內容文字中使用
<br>— 強制換行不考慮實際渲染的字型寬度。自然換行的文字加上一個<br>會產生額外的不必要的換行,導致重疊。請改用max-width讓文字自動換行。例外情況:簡短的顯示標題,其中每個字詞刻意獨佔一行(例如 130px 的 "THE\nIMMORTAL\nGAME")。
場景轉場(不可協商)
每個多場景合成必須遵循以下所有規則。違反其中任何一條都會導致合成中斷。
- 在場景之間「務必」使用轉場。 沒有跳接。沒有例外。
- 每個場景「務必」使用入場動畫。 每個元素都透過
gsap.from()動畫進入。沒有元素可以完整成形地出現。如果一個場景有 5 個元素,就需要 5 個入場補間。 - 除了最後一個場景外,「絕對不要」使用離場動畫。 這意味著:在觸發轉場之前,不要有
gsap.to()將透明度動畫至 0、將 y 動畫至畫面外、將 scale 動畫至 0,或任何其他「離開」動畫。轉場本身就是離場。在轉場開始的那一刻,離開場景的內容必須完全可見。 - 僅限最後一個場景: 最後一個場景可以淡出元素(例如淡出至黑色)。這是唯一允許使用
gsap.to(..., { opacity: 0 })的場景。
錯誤示範 — 轉場前的離場動畫:
// 禁止 — 這會在轉場可以作用之前清空場景
tl.to("#s1-title", { opacity: 0, y: -40, duration: 0.4 }, 6.5);
tl.to("#s1-subtitle", { opacity: 0, duration: 0.3 }, 6.7);
// 轉場作用在空影格上
正確示範 — 僅入場,轉場處理離場:
// 場景 1 入場動畫
tl.from("#s1-title", { y: 50, opacity: 0, duration: 0.7, ease: "power3.out" }, 0.3);
tl.from("#s1-subtitle", { y: 30, opacity: 0, duration: 0.5, ease: "power2.out" }, 0.6);
// 沒有離場補間 — 在 7.2 秒的轉場處理場景切換
// 場景 2 入場動畫
tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0);
動畫防護措施
- 將第一個動畫偏移 0.1-0.3 秒(不在 t=0)
- 在入場補間之間變化緩動函數 — 每個場景至少使用 3 種不同的緩動函數
- 不要在一個場景內重複入場模式
- 避免在深色背景上使用全螢幕線性漸層(H.264 色帶 — 使用放射狀或純色 + 局部光暈)
- 已渲染影片的標題使用 60px+,內文使用 20px+,資料標籤使用 16px+
- 在數字欄位上使用
font-variant-numeric: tabular-nums
如果未提供 visual-style.md 或動畫方向,請遵循 house-style.md 以獲得美學預設值。
字型和資產
- 字型: 直接在你的 CSS 中寫下你想要的
font-family— 編譯器會自動內嵌支援的字型。如果不支援某個字型,編譯器會發出警告。 - 為外部媒體加入
crossorigin="anonymous"
爲
…
[已截斷,待翻譯]