HyperFrames 注册表
注册表提供可通过 hyperframes add <name> 安装的可复用块和组件。
- 块 (Blocks) —— 独立的子合成（拥有自己的尺寸、时长和时间线）。通过宿主合成中的
data-composition-src包含进来。 - 组件 (Components) —— 效果片段（没有自己的尺寸）。直接粘贴到宿主合成的 HTML 中。
何时使用本技能
- 用户提到
hyperframes add、“块”、“组件”或hyperframes.json - 会话中出现
hyperframes add的输出（文件路径、剪贴板片段） - 你需要将已安装的项集成到现有合成中
- 你想发现注册表中可用的内容
快速参考
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 粘贴到脚本中（如果有的话）：
- 读取已安装的文件（例如
compositions/components/grain-overlay.html） - 将 HTML 元素复制到合成的
<div data-composition-id="...">中 - 将
<style>块复制到合成的样式区域 - 将任何
<script>内容复制到合成的脚本中（在你的时间线代码之前） - 如果组件暴露了 GSAP 时间线集成（参见片段中的注释块），将这些调用添加到你的时间线中
完整详情请参阅 wiring-components.md。
发现可用项
浏览可用的项：
# 读取注册表 manifest
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
每个项的 registry-item.json 包含：名称、类型、标题、描述、标签、尺寸（仅块）、时长（仅块）和文件列表。
有关按类型和标签筛选的详情，请参阅 discovery.md。