hyperframes-registry

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"
  }
}

详见 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 粘贴到脚本中（如果有）：

1. 读取安装的文件（例如 compositions/components/grain-overlay.html）
2. 将 HTML 元素复制到合成的 <div data-composition-id="..."> 中
3. 将 <style> 块复制到合成的样式中
4. 将任何 <script> 内容复制到合成的脚本中（在时间线代码之前）
5. 如果组件暴露了 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。