2026/9/10 20:54:39
FEATURED · 精选文章 
HyperFrames 变量与媒体系统完全指南声明式参数注入与多层级媒体时间轴解析【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames 以「写 HTML、渲视频」为核心设计其变量Variables与媒体Media机制共同决定了「什么从 HTML 外部流入画面」运行时参数通过data-composition-variables声明并在渲染时被 CLI 覆盖外部视频/音频则通过video/audio元素在任意嵌套深度被自动发现与调度。本文以 skills/hyperframes-core/references/variables-and-media.md 为骨架结合仓库源码与 lint 规则系统讲解变量声明、声明式绑定、CSS 变量注入、两种 JSON 形状的区分以及媒体时间轴基准data-start rebase、音频混音约束与预览/渲染一致性保障帮助你在自己的合成composition中写出可参数化、可复用的 HTML 视频模板。一、为什么把变量与媒体放在一起讲两者虽然独立但归属同一个问题控制「从 HTML 外部流入」的内容。变量是运行时参数标题文案、强调色、图片地址媒体是外部文件视频、音频。它们的共同特征是——值不在 HTML 内部硬编码而是在预览、渲染、Studio 编辑三个环境里保持一致地解析。理解了这一点就能理解文档为何将二者归为一组它们共用同一套作用域链composition 作用域与同一套「预览即渲染」的一致性保障机制。二、变量从声明到注入的完整链路2.1 在html上声明变量在html元素上通过data-composition-variables声明变量每条声明需要id、type、label和defaulthtml >img classclip>const { title, accent } window.__hyperframes.getVariables(); document.getElementById(title).textContent title;getVariables返回的是部分类型PartialT因为并非每个声明变量都有 default、也并非每个覆盖键都已被声明。源码建议调用方自行提供兜底getVariables.tsconst { title Untitled, theme light } getVariablesMyVars();注意变量在渲染过程中不会变化所以应在初始化时读取一次绝不能放进动画 tick 里每帧读取。枚举值越界时运行时会回退到声明默认值并打印runtime_unknown_enum_value告警getVariables.ts保证一个坏值永远不会破坏某一帧同时去重避免 Studio 重挂载时刷屏。2.4 变量规则速查支持的类型及 Studio 编辑 UI 消费的附加选项string— 可选placeholder、maxLengthnumber— 可选min、max、step、unitcolor— 无附加选项boolean— 无附加选项enum—必填options: [{ value: ..., label: ... }, ...]此外仓库类型系统还支持font对象{name, source}或字符串兜底与image对象{url}或字符串兜底见 packages/core/src/runtime/validateVariables.ts始终提供有用的default值这样预览在没有 CLI 覆盖时也能正常工作。子合成实例级覆盖用data-variable-values{title:Pro}写在子合成宿主元素上。渲染期覆盖用npx hyperframes render --variables {title:Q4 Report}或--variables-file。CI 中加--strict-variables把未声明键、类型不匹配、不在options里的枚举值从警告升级为错误。变量值在初始化时读取一次不要在动画 tick 中重复读取。媒体调色color grading可以在data-color-gradingJSON 中引用变量把$gradingPreset或${gradingIntensity}作为整个字段值运行时会在应用 shader 调整、finishing 细节、模糊/像素化效果与自定义 LUT 之前从当前 composition 的变量中解析它。2.5 两种容易混淆的 JSON 形状这是最常见的踩坑点务必区分data-composition-variables是声明数组schema[{id, type, label, default}, ...]--variables和data-variable-values是以 id 为键的值对象values{ title: Q4, accent: #fff }前者的作用是把变量「定义出来」并描述类型后者的作用是给已定义的变量「赋值」。类型校验只发生在值对象与声明数组比对时validateVariables.ts--variables里出现未声明键、或值类型与声明类型不符才会产生 issue 并在--strict-variables下终止渲染。三、媒体任意深度的自动发现与时间轴基准3.1 媒体元素在任意嵌套深度都可用video/audio可以放在任何嵌套深度包括子合成template内部或一个包装div里。运行时的发现与解析机制是见 packages/core/src/runtime/init.ts 中多处document.querySelectorAll(video, audio)以及第 678、3238 行的closest([data-composition-id])用扁平化的document.querySelectorAll(video, audio)发现全部媒体元素通过element.closest([data-composition-id])解析每个元素所属的宿主 composition按所有祖先 composition 的绝对起始时间累加 rebase该元素的局部data-start。举例宿主 composition 的 slot 在根时间2其内部子合成的媒体data-start2那么该媒体在根时间轴上从4开始——预览、快照snapshot、音轨提取extraction与最终渲染四者一致。旧项目如果刻意按根时间写媒体起始必须给元素加data-hf-media-start-basisglobal标记绝不能靠「数字是否重叠」去猜基准新合成一律使用 scene-local 的data-start。如果某个面板渲染后一片空白应抓取逐帧snapshot并视为渲染阻断问题处理。3.2 真正的约束在时间轴不在媒体位置媒体可以任意摆放但子合成的时间轴无法触及或驱动宿主元素无论是document.querySelector(#host-id)还是 gsap 选择器字符串tl.to(#host-id, …)都无法跨越 composition 边界——子合成时间轴只能驱动自身子树。因此如果媒体元素位于宿主根上它的逐场景运动缩放/透明度/morph/tilt/breathing必须写在index.html的 MAIN 时间轴上使用全局时间scene-local 时间 该场景 slot 的data-start。更简单的做法是把媒体放进场景子合成内部让子合成自己的时间轴用 scene-local 时间驱动它。对于没有 perspective 父级的 3D tilt请在元素上使用 gsap 的transformPerspective。此模式可对照 skills/hyperframes-core/references/composition-patterns.md 中的 archetype B。3.3 视频必须静音内联音频必须独立元素视频元素必须muted且playsinline即使与视频共用同一个源文件音频也必须放在独立的audio元素上video ida-roll classclip srcassets/demo.mp4 contenteditable="false">【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
HyperFrames 变量与媒体系统完全指南：声明式参数注入与多层级媒体时间轴解析
HyperFrames 变量与媒体系统完全指南声明式参数注入与多层级媒体时间轴解析【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames 以「写 HTML、渲视频」为核心设计其变量Variables与媒体Media机制共同决定了「什么从 HTML 外部流入画面」运行时参数通过data-composition-variables声明并在渲染时被 CLI 覆盖外部视频/音频则通过video/audio元素在任意嵌套深度被自动发现与调度。本文以 skills/hyperframes-core/references/variables-and-media.md 为骨架结合仓库源码与 lint 规则系统讲解变量声明、声明式绑定、CSS 变量注入、两种 JSON 形状的区分以及媒体时间轴基准data-start rebase、音频混音约束与预览/渲染一致性保障帮助你在自己的合成composition中写出可参数化、可复用的 HTML 视频模板。一、为什么把变量与媒体放在一起讲两者虽然独立但归属同一个问题控制「从 HTML 外部流入」的内容。变量是运行时参数标题文案、强调色、图片地址媒体是外部文件视频、音频。它们的共同特征是——值不在 HTML 内部硬编码而是在预览、渲染、Studio 编辑三个环境里保持一致地解析。理解了这一点就能理解文档为何将二者归为一组它们共用同一套作用域链composition 作用域与同一套「预览即渲染」的一致性保障机制。二、变量从声明到注入的完整链路2.1 在html上声明变量在html元素上通过data-composition-variables声明变量每条声明需要id、type、label和defaulthtml >img classclip>const { title, accent } window.__hyperframes.getVariables(); document.getElementById(title).textContent title;getVariables返回的是部分类型PartialT因为并非每个声明变量都有 default、也并非每个覆盖键都已被声明。源码建议调用方自行提供兜底getVariables.tsconst { title Untitled, theme light } getVariablesMyVars();注意变量在渲染过程中不会变化所以应在初始化时读取一次绝不能放进动画 tick 里每帧读取。枚举值越界时运行时会回退到声明默认值并打印runtime_unknown_enum_value告警getVariables.ts保证一个坏值永远不会破坏某一帧同时去重避免 Studio 重挂载时刷屏。2.4 变量规则速查支持的类型及 Studio 编辑 UI 消费的附加选项string— 可选placeholder、maxLengthnumber— 可选min、max、step、unitcolor— 无附加选项boolean— 无附加选项enum—必填options: [{ value: ..., label: ... }, ...]此外仓库类型系统还支持font对象{name, source}或字符串兜底与image对象{url}或字符串兜底见 packages/core/src/runtime/validateVariables.ts始终提供有用的default值这样预览在没有 CLI 覆盖时也能正常工作。子合成实例级覆盖用data-variable-values{title:Pro}写在子合成宿主元素上。渲染期覆盖用npx hyperframes render --variables {title:Q4 Report}或--variables-file。CI 中加--strict-variables把未声明键、类型不匹配、不在options里的枚举值从警告升级为错误。变量值在初始化时读取一次不要在动画 tick 中重复读取。媒体调色color grading可以在data-color-gradingJSON 中引用变量把$gradingPreset或${gradingIntensity}作为整个字段值运行时会在应用 shader 调整、finishing 细节、模糊/像素化效果与自定义 LUT 之前从当前 composition 的变量中解析它。2.5 两种容易混淆的 JSON 形状这是最常见的踩坑点务必区分data-composition-variables是声明数组schema[{id, type, label, default}, ...]--variables和data-variable-values是以 id 为键的值对象values{ title: Q4, accent: #fff }前者的作用是把变量「定义出来」并描述类型后者的作用是给已定义的变量「赋值」。类型校验只发生在值对象与声明数组比对时validateVariables.ts--variables里出现未声明键、或值类型与声明类型不符才会产生 issue 并在--strict-variables下终止渲染。三、媒体任意深度的自动发现与时间轴基准3.1 媒体元素在任意嵌套深度都可用video/audio可以放在任何嵌套深度包括子合成template内部或一个包装div里。运行时的发现与解析机制是见 packages/core/src/runtime/init.ts 中多处document.querySelectorAll(video, audio)以及第 678、3238 行的closest([data-composition-id])用扁平化的document.querySelectorAll(video, audio)发现全部媒体元素通过element.closest([data-composition-id])解析每个元素所属的宿主 composition按所有祖先 composition 的绝对起始时间累加 rebase该元素的局部data-start。举例宿主 composition 的 slot 在根时间2其内部子合成的媒体data-start2那么该媒体在根时间轴上从4开始——预览、快照snapshot、音轨提取extraction与最终渲染四者一致。旧项目如果刻意按根时间写媒体起始必须给元素加data-hf-media-start-basisglobal标记绝不能靠「数字是否重叠」去猜基准新合成一律使用 scene-local 的data-start。如果某个面板渲染后一片空白应抓取逐帧snapshot并视为渲染阻断问题处理。3.2 真正的约束在时间轴不在媒体位置媒体可以任意摆放但子合成的时间轴无法触及或驱动宿主元素无论是document.querySelector(#host-id)还是 gsap 选择器字符串tl.to(#host-id, …)都无法跨越 composition 边界——子合成时间轴只能驱动自身子树。因此如果媒体元素位于宿主根上它的逐场景运动缩放/透明度/morph/tilt/breathing必须写在index.html的 MAIN 时间轴上使用全局时间scene-local 时间 该场景 slot 的data-start。更简单的做法是把媒体放进场景子合成内部让子合成自己的时间轴用 scene-local 时间驱动它。对于没有 perspective 父级的 3D tilt请在元素上使用 gsap 的transformPerspective。此模式可对照 skills/hyperframes-core/references/composition-patterns.md 中的 archetype B。3.3 视频必须静音内联音频必须独立元素视频元素必须muted且playsinline即使与视频共用同一个源文件音频也必须放在独立的audio元素上video ida-roll classclip srcassets/demo.mp4 contenteditable="false">【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
