HyperFrames 登錄系統
此登錄系統提供可透過 hyperframes add <名稱> 安裝的可重複使用區塊與元件。
- 區塊 — 獨立的子組合(擁有自己的尺寸、持續時間與時間軸)。透過宿主組合中的
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 <目錄> --example <名稱>。
安裝位置
區塊預設安裝至 compositions/<名稱>.html。
元件預設安裝至 compositions/components/<名稱>.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 貼入腳本(若有的話):
- 讀取已安裝的檔案(例如
compositions/components/grain-overlay.html) - 將 HTML 元素複製到組合的
<div data-composition-id="...">中 - 將
<style>區塊複製到組合的樣式中 - 將任何
<script>內容複製到組合的腳本中(位於時間軸程式碼之前) - 若元件提供了 GSAP 時間軸整合(請參閱片段中的註解區塊),請將這些呼叫加入時間軸
完整細節請參閱 wiring-components.md。
探索
瀏覽可用項目:
# 讀取登錄清單
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
每個項目的 registry-item.json 包含:名稱、類型、標題、描述、標籤、尺寸(僅區塊)、持續時間(僅區塊)以及檔案列表。
按類型和標籤篩選的詳細說明請參閱 discovery.md。
貢獻新的區塊或元件
若要撰寫全新的登錄項目(字幕樣式、VFX 區塊、轉場效果、下三分之一圖卡或可重複使用的元件),並以向上游 Pull Request 的方式發布(而非安裝現有項目),請遵循完整的「構想→建立框架→建置→驗證→預覽→發布」工作流程,詳見 contributing.md。可複製貼上的入門範本(字幕 / VFX / 元件 / registry-item.json)位於 templates.md。