HyperFrames 注册表
该注册表提供了可通过 hyperframes add <名称> 安装的可重用块和组件。
- 块 — 独立的子组合(拥有自己的尺寸、持续时间、时间线)。通过宿主组合中的
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 <名称>。
安装位置
块默认安装到 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— 图层顺序(值越大越靠前)
有关完整详细信息,请参阅 wiring-blocks.md。
连接组件
组件是片段——将其 HTML 粘贴到组合的标记中,将其 CSS 粘贴到样式块中,将其 JS 粘贴到脚本中(如果有):
- 读取已安装的文件(例如
compositions/components/grain-overlay.html) - 将 HTML 元素复制到你的组合的
<div data-composition-id="...">中 - 将
<style>块复制到你的组合的样式中 - 将任何
<script>内容复制到你的组合的脚本中(在你的时间线代码之前) - 如果组件暴露了 GSAP 时间线集成(参见片段中的注释块),将这些调用添加到你的时间线中
有关完整详细信息,请参阅 wiring-components.md。
发现
浏览可用项:
# 读取注册表清单
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。