framevideo-registry

FrameVideo 注册表

适用场景

在以下情况下使用此技能：

• 安装区块 — 使用 framevideo add <block-name> 安装可复用的合成
• 安装组件 — 使用 framevideo add <component-name> 安装特效片段
• 接入区块 — 将已安装的区块集成到宿主合成中
• 合并组件 — 将组件片段粘贴到现有 HTML 中
• 发现注册表内容 — 查找可用的区块／组件
• 配置 — 管理 framevideo.json 注册表设置

请勿使用

以下情况请勿使用此技能：

• 示例模板 — 请改用 framevideo init --example <name>
• 编写自定义合成 — 请改用 framevideo 技能
• 资源预处理 — 请使用 framevideo-media
• CLI 命令（init、render 等） — 请使用 framevideo-cli

---

快速入门

安装并接入区块

# 1. Install block
npx framevideo add data-chart

# 2. Wire into host composition (index.html)
<div
  data-composition-id="data-chart"
  data-composition-src="compositions/data-chart.html"
  data-start="2"
  data-duration="5"
  data-track-index="3"
></div>

安装并合并组件

# 1. Install component
npx framevideo add grain-overlay

# 2. Copy snippet from CLI output
# 3. Paste into your composition HTML
# Component snippets merge directly into HTML (no data-composition-src)

---

区块与组件的区别

类型	描述	安装位置	使用方法
区块	独立子合成	compositions/<name>.html	通过 data-composition-src 引入
组件	特效片段	compositions/components/<name>.html	直接粘贴到 HTML 中

---

何时使用此技能

• 用户提到 framevideo add、“区块”、“组件”或 framevideo.json
• 会话中出现 framevideo add 的输出（文件路径、剪贴板片段）
• 你需要将已安装的项目接入现有合成
• 你想了解注册表中有哪些可用内容

快速参考

framevideo add data-chart              # install a block
framevideo add grain-overlay           # install a component
framevideo add shimmer-sweep --dir .   # target a specific project
framevideo add data-chart --json       # machine-readable output
framevideo add data-chart --no-clipboard  # skip clipboard (CI/headless)

安装完成后，CLI 会显示写入了哪些文件，并提供一段可粘贴到宿主合成中的片段。该片段只是起点——接入区块时，你需要添加 data-composition-id（必须与区块的内部合成 ID 匹配）、data-start 和 data-track-index 属性。

注意：framevideo add 仅适用于区块和组件。对于示例，请改用 framevideo init <dir> --example <name>。

安装位置

默认情况下，区块会安装到 compositions/<name>.html。 默认情况下，组件会安装到 compositions/components/<name>.html。

这些路径可在 framevideo.json 中配置：

{
  "registry": "https://raw.githubusercontent.com/chanjing/framevideo/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。

发现

浏览可用项目：

# Read the registry manifest
curl -s https://raw.githubusercontent.com/chanjing/framevideo/main/registry/registry.json

每个项目的 registry-item.json 都包含：名称、类型、标题、描述、标签、尺寸（仅区块）、时长（仅区块）和文件列表。

有关按类型和标签筛选的详情，请参阅 discovery.md。