用途
HyperFrames Registry 为 HyperFrames 提供可复用的块与组件,用户可通过 hyperframes add <name> 安装,并将其接入 HyperFrames 合成。
主要能力
- 注册表包含两种条目:
- 块(Blocks):独立的子合成,拥有自己的尺寸、时长和时间线,通过
data-composition-src嵌入宿主合成。 - 组件(Components):效果片段,没有独立尺寸,需粘贴到宿主合成的 HTML 中。
- 块(Blocks):独立的子合成,拥有自己的尺寸、时长和时间线,通过
- 支持浏览注册表清单和条目元数据(名称、类型、标题、描述、标签、尺寸、时长、文件列表)。
使用方式
常用命令:
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"
}
}
接入块时,在宿主 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(层序,数值越大越靠前)。
接入组件时,读取已安装文件,将 HTML 元素复制到合成的 <div data-composition-id="..."> 中,将 <style> 块复制到合成样式,将 <script> 内容复制到合成脚本(位于时间线代码之前);若组件提供 GSAP 时间线集成(见片段注释块),还需将这些调用加入时间线。
查看注册表清单:
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
每个条目的 registry-item.json 包含名称、类型、标题、描述、标签、尺寸(仅块)、时长(仅块)和文件列表。
适用场景
- 用户提到
hyperframes add、block、component 或hyperframes.json。 - 会话中出现
hyperframes add的输出(文件路径、剪贴板片段)。 - 需要将已安装条目接入现有合成。
- 查看注册表中可用的块与组件。
限制
hyperframes add 仅支持块和组件,不用于示例;示例需使用 hyperframes init <dir> --example <name>。其他限制暂未提供。