hyperframes-registry

HyperFrames 註冊表

註冊表提供可透過 hyperframes add <name> 安裝的可重複使用區塊和元件。

• 區塊 — 獨立的子合成（有自己的尺寸、時長、時間軸）。透過主合成中的 data-composition-src 引入。
• 元件 — 效果片段（沒有自己的尺寸）。直接貼入主合成的 HTML 中。

快速參考

hyperframes add data-chart              # 安裝區塊
hyperframes add grain-overlay           # 安裝元件
hyperframes add shimmer-sweep --dir .   # 指定專案目錄
hyperframes add data-chart --json       # 機器可讀輸出
hyperframes add data-chart --no-clipboard  # 跳過剪貼簿（CI/無頭模式）

安裝後，CLI 會顯示寫入了哪些檔案，以及要貼入主合成的程式碼片段。該片段僅為起點 — 接入區塊時，你需要自行加入 data-composition-id（必須與區塊內部的合成 ID 相符）、data-start 和 data-track-index 屬性。

注意：hyperframes add 僅適用於區塊和元件。若要使用範例，請改用 hyperframes init <dir> --example <name>。

安裝位置

區塊預設安裝至 compositions/<name>.html。
元件預設安裝至 compositions/components/<name>.html。

這些路徑可在 hyperframes.json 中設定：

{
  "registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
  "paths": {
    "blocks": "compositions",
    "components": "compositions/components",
    "assets": "assets"
  }
}

完整細節請參閱 install-locations.md。

接入區塊

區塊是獨立的合成 — 透過主 index.html 中的 data-composition-src 引入：

<div
  data-composition-id="data-chart"
  data-composition-src="compositions/data-chart.html"
  data-start="2"
  data-duration="15"
  data-track-index="1"
  data-width="1920"
  data-height="1080"
></div>

關鍵屬性：

• data-composition-src — 區塊 HTML 檔案的路徑
• data-composition-id — 必須與區塊內部的 ID 相符
• data-start — 區塊在主合成時間軸中出現的時間（秒）
• data-duration — 區塊播放的長度
• data-width / data-height — 區塊畫布尺寸
• data-track-index — 圖層順序（數字越大越靠前）

完整細節請參閱 wiring-blocks.md。

接入元件

元件是片段 — 將其 HTML 貼入合成的標記中，CSS 貼入樣式區塊，JS 貼入腳本（如果有的話）：

1. 讀取已安裝的檔案（例如 compositions/components/grain-overlay.html）
2. 將 HTML 元素複製到合成的 <div data-composition-id="..."> 中
3. 將 <style> 區塊複製到合成的樣式中
4. 將任何 <script> 內容複製到合成的腳本中（在時間軸程式碼之前）
5. 如果元件暴露了 GSAP 時間軸整合（請參閱片段中的註解區塊），將這些呼叫加入你的時間軸

完整細節請參閱 wiring-components.md。

探索

瀏覽可用的項目：

# 讀取註冊表清單
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json

每個項目的 registry-item.json 包含：名稱、類型、標題、描述、標籤、尺寸（僅區塊）、時長（僅區塊）和檔案列表。

關於按類型和標籤篩選的詳細資訊，請參閱 discovery.md。

貢獻新的區塊或元件

若要編寫一個全新的註冊表項目（字幕樣式、VFX 區塊、轉場、下三分之一或可重複使用的元件）並以 PR 形式提交至上游 — 而非安裝現有項目 — 請遵循 contributing.md 中完整的構想 → 建立框架 → 建置 → 驗證 → 預覽 → 發佈工作流程。可複製貼上的入門範本（字幕 / VFX / 元件 / registry-item.json）位於 templates.md。