貢獻至 HyperFrames 註冊表
引導使用者從構想到合併 PR,建立新的註冊表區塊或元件。
工作流程
1. 釐清 → 2. Scaffold → 3. 建構 → 4. 驗證 → 5. 預覽 → 6. 發佈
步驟 1:釐清
詢問他們正在構建的內容。註冊表有兩種項目類型:
- 區塊 (
registry/blocks/,類型hyperframes:block) — 具有固定尺寸和時長的完整獨立合成。字幕樣式、VFX 效果、標題卡、下三分之一。 - 元件 (
registry/components/,類型hyperframes:component) — 沒有固定尺寸或時長的可重複使用片段。CSS 效果、文字處理、可適應任何合成大小的覆蓋層。
然後詢問:
- 效果的單句描述
- 視覺參考(URL、螢幕截圖或描述)
- 誰在何時使用這個?
步驟 2:Scaffold
建立註冊表結構:
對於區塊:
registry/blocks/{block-name}/
{block-name}.html
registry-item.json
對於元件:
registry/components/{component-name}/
{component-name}.html
registry-item.json
命名慣例:
| 項目名稱 | ID 前綴 | 範例 ID |
|---|---|---|
cap-hormozi | hz | hz-cg-0, hz-cw-3 |
cap-typewriter | tw | tw-cg-0, tw-ch-0-5 |
vfx-chrome | vc | vc-canvas |
使用 2-3 個字母的前綴。所有元素 ID 都必須使用此前綴,以避免在子合成中發生衝突。
區塊的 registry-item.json:
{
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
"name": "{block-name}",
"type": "hyperframes:block",
"title": "{Human Title}",
"description": "{one sentence}",
"dimensions": { "width": 1920, "height": 1080 }, // 調整:直式/社交媒體為 1080x1920
"duration": 10, // 根據您的合成調整
"tags": ["{category}", "{subcategory}"],
"files": [
{
"path": "{block-name}.html",
"target": "compositions/{block-name}.html",
"type": "hyperframes:composition"
}
]
}
元件的 registry-item.json(無 dimensions 或 duration):
{
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
"name": "{component-name}",
"type": "hyperframes:component",
"title": "{Human Title}",
"description": "{one sentence}",
"tags": ["{category}"],
"files": [
{
"path": "{component-name}.html",
"target": "compositions/components/{component-name}.html",
"type": "hyperframes:snippet"
}
]
}
步驟 3:建構
根據類型套用正確的範本。請參閱 templates.md 以取得可直接複製貼上的入門程式碼。
字幕區塊
不可妥協的字幕規則:
- 字型:比例字型最小 96px。等寬字型可接受 64-72px(較寬的字元需要較小的尺寸)。
- 可讀性:
-webkit-text-stroke: 2-3px或 多層text-shadow - 溢出:在每個群組上呼叫
window.__hyperframes.fitTextFontSize() - Karaoke:透過
tl.to(wordEl, { color/scale }, WORDS[wi].start)高亮當前單字 - 硬性終止:在每個群組上使用
tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end) - 永遠不要在与
tl.set(el, { opacity: 1 })相同的位置使用tl.from(el, { opacity: 0 })— from 會覆蓋 set。請改用tl.to。
逐字元動畫(打字機、亂碼效果):
- 將每個字元包裹在
<span>中,ID 為{prefix}-ch-{group}-{char} - 透過在計算的時間間隔(來自單字時間戳)執行
tl.set來交錯 - 游標/裝飾元素:使用
tl.set以間隔執行 — 不要使用 CSS 動畫(不可隨意定位)
定位變體:
- 置中:
display: flex; align-items: center; justify-content: center; - 下三分之一:
position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center; - 靠左對齊:
position: absolute; bottom: 100px; left: 120px; text-align: left;
VFX 區塊(Three.js)
- 從 CDN 使用
[email protected](全域腳本) tl.eventCallback("onUpdate", renderScene); renderScene();— 不要使用requestAnimationFrame- 狀態代理模式:GSAP 動畫化純 JS 物件,渲染函式讀取它
- 使用種子 PRNG (
mulberry32) 來處理隨機性
所有類型
data-composition-id必須與window.__timelines["id"]匹配- 所有元素 ID 前綴為區塊縮寫
gsap.timeline({ paused: true })— 總是暫停- 不要使用
Math.random(),不要使用Date.now()
步驟 4:驗證
hyperframes lint # 必須為 0 個錯誤
hyperframes validate --no-contrast # 必須為 0 個控制台錯誤
步驟 5:預覽
# 渲染預覽影片
hyperframes render -o preview.mp4
# 為視覺 QA 建立快照
hyperframes snapshot --at "1.0,3.0,5.0,7.0"
# 發佈到 hyperframes.dev 供審閱
npx hyperframes publish
目錄預覽圖片 — 目錄卡片使用位於 docs/images/catalog/{kind}/{name}.png 的 PNG(其中 {kind} 是 blocks 或 components)。從快照生成它,然後:
- HeyGen 內部貢獻者: 執行
scripts/upload-docs-images.sh(需要 AWS 設定檔engineering-767398024897) - 外部貢獻者: 將預覽 MP4 附加到您的 PR 描述中。維護人員將在合併之前生成並上傳目錄圖片。
步驟 6:發佈
所有步驟都是必需的。缺少任何一個都會產生損壞的目錄條目。
{kind} 是 blocks 或 components,取決於您在步驟 1 中建構的內容。
# 1. 建立分支
git checkout -b feat/registry-{name}
# 2. 格式化 HTML
npx oxfmt registry/{kind}/{name}/*.html
# 3. 更新 registry/registry.json — 將條目新增到 "items" 陣列:
# { "name": "{name}", "type": "hyperframes:block" } (或 "hyperframes:component")
# 4. 生成目錄文件頁面
npx tsx scripts/generate-catalog-pages.ts
# 5. 發佈到 hyperframes.dev 以便審閱者預覽
npx hyperframes publish
# 6. 暫存所有內容
git add registry/{kind}/{name}/ registry/registry.json docs/catalog/
# 7. 提交
git commit -m "feat(registry): add {name} — {one sentence}"
# 8. 推送並開啟包含 hyperframes.dev 連結的 PR
git push origin feat/registry-{name}
gh pr create --title "feat(registry): {name}" --body "preview: {hyperframes.dev-url}"
如果您沒有 GitHub 帳戶: 您需要一個才能開啟 PR。請在 https://github.com/signup 註冊,然後執行 gh auth login。
品質關卡
-
hyperframes lint→ 0 個錯誤 -
hyperframes validate→ 0 個控制台錯誤 -
npx oxfmt --check通過 - 已更新
registry/registry.json並包含新條目 - 已執行
scripts/generate-catalog-pages.ts(已生成文件頁面) - 已執行
npx hyperframes publish(聲明您的專案 URL) - 預覽 MP4 已附加到 PR(外部)或目錄 PNG 已上傳(內部)
- 所有 ID 唯一且已加前綴