为 HyperFrames Registry 贡献
引导用户从想法到合并 PR 的新注册表区块或组件。
工作流
1. 明确 → 2. 搭建 → 3. 构建 → 4. 验证 → 5. 预览 → 6. 发布
第一步:明确
询问用户要构建什么。注册表有两种项目类型:
- 区块 (
registry/blocks/,类型hyperframes:block)——一个完全独立的合成,具有固定尺寸和时长。字幕样式、VFX 效果、标题卡、下三分之一。 - 组件 (
registry/components/,类型hyperframes:component)——一个可重用的代码片段,无固定尺寸或时长。CSS 效果、文本处理、可适应任何合成尺寸的叠加层。
然后询问:
- 效果的一句话描述
- 视觉参考(URL、截图或描述)
- 谁在什么情况下使用这个?
第二步:搭建
创建注册表结构:
对于区块:
registry/blocks/{区块名称}/
{区块名称}.html
registry-item.json
对于组件:
registry/components/{组件名称}/
{组件名称}.html
registry-item.json
命名约定:
| 项目名称 | ID 前缀 | 示例 ID |
|---|---|---|
cap-hormozi | hz | hz-cg-0, hz-cw-3 |
cap-typewriter | tw | tw-cg-0, tw-ch-0-5 |
vfx-chrome | vc | vc-canvas |
使用 2-3 个字母的前缀。所有元素 ID 必须使用此前缀,以避免在子合成中发生冲突。
区块的 registry-item.json:
{
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
"name": "{区块名称}",
"type": "hyperframes:block",
"title": "{人类可读标题}",
"description": "{一句话描述}",
"dimensions": { "width": 1920, "height": 1080 }, // 调整:竖屏/社交为 1080x1920
"duration": 10, // 根据合成调整
"tags": ["{类别}", "{子类别}"],
"files": [
{
"path": "{区块名称}.html",
"target": "compositions/{区块名称}.html",
"type": "hyperframes:composition"
}
]
}
组件的 registry-item.json(无 dimensions 或 duration):
{
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
"name": "{组件名称}",
"type": "hyperframes:component",
"title": "{人类可读标题}",
"description": "{一句话描述}",
"tags": ["{类别}"],
"files": [
{
"path": "{组件名称}.html",
"target": "compositions/components/{组件名称}.html",
"type": "hyperframes:snippet"
}
]
}
第三步:构建
根据类型应用正确的模板。参见 templates.md 获取可复制粘贴的入门代码。
字幕块
不可协商的字幕规则:
- 字体:比例字体最小 96px。等宽字体可接受 64-72px(更宽的字符需要更小的尺寸)。
- 可读性:
-webkit-text-stroke: 2-3px或多层text-shadow - 溢出:在每个组上调用
window.__hyperframes.fitTextFontSize() - 卡拉 OK:通过
tl.to(wordEl, { color/scale }, WORDS[wi].start)高亮当前词 - 硬性终止:在每个组上使用
tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end) - 永远不要在
tl.set(el, { opacity: 1 })的同一位置使用tl.from(el, { opacity: 0 })——from 会覆盖 set。请改用tl.to。
逐字符动画(打字机、乱码):
- 将每个字符包裹在带有 ID
{prefix}-ch-{group}-{char}的<span>中 - 通过从时间戳计算间隔的
tl.set进行错开 - 光标/装饰性元素:使用
tl.set在间隔处设置——不要用 CSS 动画(不可搜索)
定位变体:
- 居中:
display: flex; align-items: center; justify-content: center; - 下三分之一:
position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center; - 左对齐:
position: absolute; bottom: 100px; left: 120px; text-align: left;
VFX 块(Three.js)
- 使用来自 CDN 的
[email protected](全局脚本) tl.eventCallback("onUpdate", renderScene); renderScene();——不要使用 requestAnimationFrame- 状态代理模式:GSAP 动画化纯 JS 对象,渲染函数读取它
- 种子化 PRNG(
mulberry32)实现随机性
所有类型
data-composition-id必须匹配window.__timelines["id"]- 所有元素 ID 带有块缩写前缀
gsap.timeline({ paused: true })——始终暂停- 不要使用
Math.random(),不要使用Date.now()
第四步:验证
hyperframes lint # 必须零错误
hyperframes validate --no-contrast # 必须零控制台错误
第五步:预览
# 渲染预览视频
hyperframes render -o preview.mp4
# 快照用于视觉 QA
hyperframes snapshot --at "1.0,3.0,5.0,7.0"
# 发布到 hyperframes.dev 以供审查
npx hyperframes publish
目录预览图像——目录卡片使用位于 docs/images/catalog/{kind}/{名称}.png 的 PNG(其中 {kind} 是 blocks 或 components)。从快照生成,然后:
- HeyGen 内部贡献者: 运行
scripts/upload-docs-images.sh(需要 AWS 配置文件engineering-767398024897) - 外部贡献者: 将预览 MP4 附加到 PR 描述中。维护者将在合并前生成并上传目录图像。
第六步:发布
所有步骤都是必需的。缺少任何一步都会导致目录条目损坏。
{kind} 是在第一步中构建的内容的 blocks 或 components。
# 1. 创建分支
git checkout -b feat/registry-{名称}
# 2. 格式化 HTML
npx oxfmt registry/{kind}/{名称}/*.html
# 3. 更新 registry/registry.json——向 "items" 数组添加条目:
# { "name": "{名称}", "type": "hyperframes:block" } (或 "hyperframes:component")
# 4. 生成目录文档页面
npx tsx scripts/generate-catalog-pages.ts
# 5. 发布到 hyperframes.dev 供审查者预览
npx hyperframes publish
# 6. 暂存所有内容
git add registry/{kind}/{名称}/ registry/registry.json docs/catalog/
# 7. 提交
git commit -m "feat(registry): 添加 {名称} — {一句话描述}"
# 8. 推送并打开带有 hyperframes.dev 链接的 PR
git push origin feat/registry-{名称}
gh pr create --title "feat(registry): {名称}" --body "preview: {hyperframes.dev-url}"
如果你没有 GitHub 账户: 你需要一个账户才能打开 PR。在 https://github.com/signup 注册,然后运行 gh auth login。
质量门禁
-
hyperframes lint→ 0 错误 -
hyperframes validate→ 0 控制台错误 -
npx oxfmt --check通过 -
registry/registry.json已更新新条目 -
scripts/generate-catalog-pages.ts已运行(文档页面已生成) -
npx hyperframes publish已运行(占用你的项目 URL) - 预览 MP4 已附加到 PR(外部)或目录 PNG 已上传(内部)
- 所有 ID 唯一并带有前缀