核心概念
数据属性
控制元素时序和行为的核心属性。
Hyperframes 使用 HTML 数据属性来控制时序、媒体播放和合成结构。这些是每个视频的声明式构建块。
时序属性
| 属性 | 示例 | 描述 |
|---|---|---|
data-start | "0" 或 "intro" | 以秒为单位的开始时间，或用于相对时序的片段 ID 引用 |
data-duration | "5" | 以秒为单位的持续时间。图片必填。视频/音频可选（默认为源文件时长）。合成上不使用。 |
data-track-index | "0" | 时间线轨道编号。控制 z 轴排序（数值越大越靠前），并将片段分组到行中。同一轨道上的片段不能重叠。 |
媒体属性
| 属性 | 示例 | 描述 |
|---|---|---|
data-media-start | "2" | 媒体播放偏移 / 裁剪点（秒）。默认值：0 |
data-volume | "0.8" | 音频/视频音量，0 到 1 |
data-has-audio | "true" | 表示视频有音轨 |
合成属性
| 属性 | 示例 | 描述 |
|---|---|---|
data-composition-id | "root" | 合成包装器的唯一 ID（每个合成必填） |
data-width | "1920" | 合成宽度（像素） |
data-height | "1080" | 合成高度（像素） |
data-composition-src | "./intro.html" | 外部合成 HTML 文件的路径 |
data-variable-values | '{"title":"Hello"}' | 传递给嵌套合成的 JSON 值对象。在子合成内部，通过 window.__hyperframes.getVariables() 读取——运行时会将这些值覆盖在子合成自身的 data-composition-variables 默认值之上，并按实例暴露合并后的结果（相同的源文件可以使用不同的值嵌入多次）。 |
data-composition-variables | '[{"id":"title","type":"string","label":"Title","default":"Hello"}]' | 声明变量的 JSON 数组（id、type、label、default）。驱动 Studio 编辑界面，并提供 window.__hyperframes.getVariables() 读取的默认值。CLI 标志 hyperframes render --variables '<json>' 在顶层渲染时覆盖这些默认值；宿主元素通过 data-variable-values 逐实例覆盖。 |
元素可见性
为所有定时元素添加 class="clip"，以便运行时管理其可见性生命周期：
<h1 id="title" class="clip"
data-start="0" data-duration="5" data-track-index="0">
Hello World
</h1>
相对时序
片段可以在 data-start 属性中引用另一个片段的 id，而不是计算绝对开始时间。这意味着"在该片段结束时开始"：
<video id="intro" data-start="0" data-duration="10" data-track-index="0" src="..."></video>
<video id="main" data-start="intro" data-duration="20" data-track-index="0" src="..."></video>
<video id="outro" data-start="main" data-duration="5" data-track-index="0" src="..."></video>
main 解析为第 10 秒，outro 解析为第 30 秒。如果 intro 的持续时间发生变化，下游片段会自动调整。
偏移（间隙和重叠）
在 ID 后添加 + N 或 - N 来设置相对于被引用片段结束时间的偏移：
<!-- intro 之后有 2 秒间隙 -->
<video id="scene-a" data-start="intro + 2" data-duration="20"
data-track-index="0" src="..."></video>
<!-- 与 intro 重叠 0.5 秒（交叉淡入淡出） -->
<video id="scene-b" data-start="intro - 0.5" data-duration="20"
data-track-index="1" src="..."></video>
ℹ️ Note
重叠的片段必须在不同的轨道上——同一轨道上的片段不能在时间上重叠。
仅限同一合成 -- 引用在片段所属父合成内解析。你不能引用兄弟或父合成中的片段。
禁止循环引用 -- 如果 B 在 A 之后开始，则 A 不能在 B 之后开始。解析器会检测循环并抛出错误。
被引用的片段必须有已知的持续时间 -- 要么有明确的 data-duration，要么有从源媒体推断出的持续时间。如果被引用的片段没有已知的持续时间，引用无法解析。
解析规则 -- 如果值是有效的数字，则视为绝对秒数。否则按以下方式解析：
<id>-- 在该片段结束时开始<id> + <number>-- 在该片段结束后 N 秒开始<id> - <number>-- 在该片段结束前 N 秒开始
链式长度 -- 引用可以链式（A -> B -> C），但深层嵌套链会使时间线难以理解。为保持可读性，建议链式层级不超过 3-4 层。
下一步
- 合成 合成如何使用数据属性定义视频结构
- HTML Schema 参考 包含每个元素详细信息的完整属性参考
- GSAP 动画 在数据属性驱动的时序旁为元素添加动画
- 常见错误 设置时序和属性时需要避免的陷阱