HyperFrames Registry
Registry 提供可重用的區塊(Blocks)與元件(Components),可透過 hyperframes add <name> 安裝。
- 區塊(Blocks) — 獨立的子組合(擁有自己的尺寸、時間長度與時間軸)。在主組合中透過
data-composition-src引入。 - 元件(Components) — 效果程式碼片段(無獨立尺寸)。直接貼入主組合的 HTML 中。
何時使用此技能
- 使用者提到
hyperframes add、「區塊(block)」、「元件(component)」或hyperframes.json - 對話中出現
hyperframes add的輸出結果(檔案路徑、剪貼簿程式碼片段) - 你需要將已安裝的項目接線至現有組合
- 你想探索 Registry 中有哪些可用項目
快速參考
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。
接線區塊
區塊是獨立的組合 — 透過 data-composition-src 在主組合的 index.html 中引入:
<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。
探索
瀏覽可用項目:
# 讀取 Registry 資訊清單
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
每個項目的 registry-item.json 包含:名稱、類型、標題、描述、標籤、尺寸(僅區塊)、時間長度(僅區塊)以及檔案列表。
根據類型和標籤篩選的詳細說明,請參閱 discovery.md。