HyperFrames 注册表
注册表提供可复用的块和组件,可通过 hyperframes add <name> 安装。
- 块——独立的子合成(拥有自己的尺寸、时长和时间线)。通过宿主合成中的
data-composition-src属性引入。 - 组件——效果片段(没有独立尺寸)。直接粘贴到宿主合成的 HTML 中。
快速参考
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"
}
}
接线块
块是独立的合成——通过 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 时间轴集成(请参见片段中的注释块),将那些调用添加到时间轴中
发现
浏览可用项目:
# 读取注册表清单
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 中找到。