外掛安裝: 在執行設定或更新命令之前,請先遵循外掛執行規則(當此技能位於 HyperFrames 外掛內部時)。獨立安裝則保留下方的更新說明。
HyperFrames 註冊表
此註冊表提供可透過 hyperframes add <名稱> 安裝的可重用區塊與元件。
- 區塊 (Blocks) — 獨立的子合成(擁有自身的尺寸、時長、時間軸)。透過
data-composition-src包含在主機合成中。 - 元件 (Components) — 效果片段(無自身尺寸)。直接貼入主機合成的 HTML 中。
快速參考
hyperframes add data-chart # 安裝一個區塊
hyperframes add grain-overlay # 安裝一個元件
hyperframes add captions # 安裝所有標記為 captions 的區塊
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 <名稱>。
安裝位置
預設情況下,區塊安裝到 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— 工作室時間軸行號;僅為顯示用途。圖層疊加請使用 CSSz-index
詳情請參閱 wiring-blocks.md。
連接元件
元件是程式碼片段 — 將其 HTML 貼入合成標記、CSS 貼入樣式區塊、JS 貼入腳本(如果有的話):
- 讀取已安裝的檔案(例如
compositions/components/grain-overlay.html) - 將 HTML 元素複製到合成的
<div data-composition-id="...">中 - 將
<style>區塊複製到合成的樣式中 - 將任何
<script>內容複製到合成的腳本中(在時間軸程式碼之前) - 如果元件暴露了 GSAP 時間軸整合(請參閱代碼片段中的註解區塊),將這些呼叫加入你的時間軸
詳情請參閱 wiring-components.md。
發現 (Discovery)
使用 CLI 作為主要的發現界面。先根據意圖搜尋,再瀏覽: 註冊表中的項目數量超過肉眼可掃描的範圍,因此列出所有項目並根據名稱或標籤進行比對是較慢的路徑,而且當作者的用詞與你的不同時,這種方法會失效。
# 根據節拍應執行的動作對整個目錄進行排名
npx hyperframes catalog --query "reveal a headline one line at a time"
npx hyperframes add caption-clip-wipe
搜尋是本機進行的,不會發送任何資料。預設情況下,它根據與項目名稱、標題和描述共享的詞彙進行排名,因此只會找到使用與你相同詞彙的項目;--on-device 則根據意義進行排名(需一次性下載模型)。使用 --json 時,信封會顯示是哪個層級回應,請據此檢查,而不是假設排名已發生。
無論影片使用何種語言,一律使用英文進行查詢。 目錄是以英文編寫的,兩個層級也都是以英文進行索引(on-device 模型也僅支援英文)。使用其他語言的查詢不會產生可搜尋的詞彙,並且會一無所獲。在日文或中文的專案中很容易犯這個錯誤——簡報、字幕和旁白都是該語言,查詢自然也會跟隨:請用英文描述 動作,然後用影片所需的語言編寫螢幕上的文字。如果查詢回傳了 No searchable words in query,這就是這個規則造成的,而不是缺少元件,也不值得回報為缺口。
可安裝性是在排名之後應用的,而不是之前:向量承載但此註冊表無法提供的項目名稱會從結果中刪除,並計入 dropped,因此非零的 dropped 表示兩者屬於不同的世代。請參閱 /hyperframes-cli 了解離線層級、同意閘門以及如何刷新過期索引。
若要瀏覽或篩選而非搜尋:
npx hyperframes catalog
npx hyperframes catalog --type block
npx hyperframes catalog --type component
npx hyperframes catalog --type block --tag social
npx hyperframes catalog --json
npx hyperframes catalog --human-friendly
普通的表格模式和 --json 模式僅列出匹配項;使用 hyperframes add <名稱> 安裝選中的項目。--human-friendly 會開啟互動式選擇器並立即安裝所選項目。在 CI 或代理工作流程中,建議先使用 --json,再明確執行 add。
回報目錄中缺少的項目
當搜尋結果中沒有符合需求的項目時,請先回報,再手動製作該動畫效果:
npx hyperframes feedback --search-miss "<你執行的查詢>" --wanted "<你需要的動畫效果>" --tier <回應的層級>
catalog --query 會印出這行命令(已預先填好),而 --json 會將其作為 report_gap 攜帶——因此在你決定沒有任何項目符合需求時,這行命令已準備就緒。
只要結果中沒有任何項目符合需求,無論是哪個層級回應,都請回報。 不要等到 on-device 層級回應:它需要一個已同意的 33 MB 下載,因此代理執行預設使用 words 層級,除非它明確選擇加入。如果只針對 on-device 進行回報,幾乎所有報告都會被忽視。--tier 值會隨附在報告中,因此當這些報告被閱讀時,詞彙失配與意義失配仍然可以區分。請描述你想要的_效果_,而不是你想像的項目名稱:回報的內容是一份有價值的動作列表,而報告一個不存在的項目名稱則毫無用處。這是唯一會將查詢發送到任何地方的路徑,這也正是為什麼它是一個單獨的、經過深思熟慮的命令,而不是搜尋自行執行的動作。它不攜帶任何評分,也永遠不會進入評分指標。
這是整個目錄的需求訊號。跳過它意味著你所遇到的缺口將只能從安裝計數中推測,而安裝計數無法看到一個沒有人能安裝的動作。
如果 CLI 無法連線到設定的註冊表,請檢查原始清單作為備用方案:
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
CLI 無法連線到的註冊表不會因發現而清空目錄:只要重新驗證失敗,之前獲取並快取的本機清單會繼續在 24 小時的刷新視窗後提供服務,因此 catalog 和 catalog --query 仍會根據磁碟上的最後一份副本進行列出和排名。
即使是你昨天安裝過的項目,add 仍然需要網路。 只有清單會被快取;項目的實際檔案每次安裝時都會重新獲取。因此,離線時你可以搜尋,也可以查看項目的內容,但安裝會因檔案獲取失敗而失敗。不要向用戶承諾可以離線安裝。
每個項目的 registry-item.json 包含:名稱、類型、標題、描述、標籤、尺寸(僅限區塊)、時長(僅限區塊)以及檔案列表。
詳情請參閱 discovery.md 了解按類型和標籤進行篩選的資訊。
貢獻新的區塊或元件
若要創作一個新的註冊表項目(如字幕樣式、VFX 區塊、轉場、下三分之一或一個可重用的元件)並將其作為上游 PR 提交——而非安裝現有的項目——請遵循 contributing.md 中完整的「構想 → 腳手架 → 建構 → 驗證 → 預覽 → 發布」工作流程。入門模板(字幕 / VFX / 元件 / registry-item.json)在 templates.md 中。