HyperFrames 注册表
注册表提供可通过 hyperframes add <name> 安装的可重用块和组件。
- 块 — 独立的子合成（拥有自己的尺寸、持续时间和时间线）。通过
data-composition-src包含在主机合成中。 - 组件 — 效果片段（无自身尺寸）。直接粘贴到主机合成的 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 <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— 必须匹配块的内部 IDdata-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。
发现
使用 CLI 作为主要发现界面。先按意图搜索，再浏览： 注册表中的项目比您用眼睛扫描的要多，因此列出它们并按名称或标签匹配是缓慢的路径，并且当作者的措辞与您的措辞不同时，它会失败。
# 根据节拍应该执行的操作对整个目录进行排名
npx hyperframes catalog --query "逐行揭示标题"
npx hyperframes add caption-clip-wipe
搜索是本地进行的，不会发送任何内容。默认情况下，它根据与项目名称、标题和描述共享的词汇进行排名，因此它只会找到重用您词语的项目；--on-device 则根据含义进行排名，需要一次性的模型下载。使用 --json 时，信封会指示哪个层级回答了问题，因此请检查该信息，而不是假设排名已完成。
可安装性在排名之后应用，而不是之前：向量携带但此注册表无法提供的名称会从结果中删除并计入 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 <name> 安装选定的名称。--human-friendly 会打开一个交互式选择器并立即安装所选项目。在 CI 或代理工作流中，优先使用 --json，然后显式执行 add。
如果 CLI 无法访问配置的注册表，请检查原始清单作为后备：
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 中复制粘贴。