HyperFrames Lottie 运行时适配器：在 HTML 合成中确定性渲染 lottie-web 与 dotLottie 动画

HyperFrames Lottie 运行时适配器在 HTML 合成中确定性渲染 lottie-web 与 dotLottie 动画【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames 通过内置的lottie运行时适配器支持对lottie-web与lottiefiles/dotlottie-web两类播放器进行确定性时间寻址seek让 After Effects 导出的动画资产能在 HTML 合成中按帧渲染。本文基于 skills/hyperframes-animation/adapters/lottie.md 展开结合 packages/core/src/runtime/adapters/lottie.ts 的源码实现与其测试用例讲解注册契约、两种播放器的接入模式、多动画同步、时长自动推断与验证流程。读完本文你将掌握在 HyperFrames 合成中正确接入 Lottie 资产、避免渲染期坑点并让导出结果确定性的完整方法。为什么 Lottie 需要专属适配器Lottie 动画.json或.lottie与 GSAP 等代码驱动的动画不同它的时间线已经以帧率 总帧数的形式编码在资产本身。HyperFrames 的运行时并不需要创建这个时间线它只需要拿到一个可被寻址的播放器对象然后在渲染时把它拨到指定的时间点即可——这正是lottie适配器的职责。从 skills/hyperframes-animation/SKILL.md 的运行时选型表可以看到HyperFrames 共有七个运行时适配器GSAP 为默认另有 Lottie、Three.js、Anime.js、CSS keyframes、Web Animations API、TypeGPU而选型原则是当资产自带预制时间线典型如 After Effects 导出时选择 Lottie。多个运行时可以在同一合成中共存各自把实例注册到运行时专属的全局变量上由 HyperFrames 一次性全部寻址。接入契约Contract任何 Lottie 合成都必须遵守 lottie.md 中定义的接入契约共五条从本地项目文件加载资产通常放在assets/目录下设置autoplay: false——播放必须完全由运行时接管优先loop: false除非用户明确要求循环把每个返回的动画或播放器注册到window.__hfLottie用 CSS 保持 Lottie 容器尺寸稳定。契约背后的原因可以从源码解释适配器的seek遍历的正是window.__hfLottie数组见 lottie.ts未注册的实例不会被寻址而autoplay/loop若为true播放器会在页面加载后自行推进时间线破坏确定性。全局注册点的类型声明位于 packages/core/src/runtime/window.d.ts注释中同样写明Push your animation instance here after callinglottie.loadAnimation()。lottie-web 模式经典 bodymovin 播放器lottie-webbodymovin是最常见的 Lottie 运行时。接入方式如下div idlogo-lottie classlottie-layer/div script srchttps://cdnjs.cloudflare.com/ajax/libs/bodymovin/5.12.2/lottie.min.js/script script const anim lottie.loadAnimation({ container: document.getElementById(logo-lottie), renderer: svg, loop: false, autoplay: false, path: assets/logo-reveal.json, }); window.__hfLottie window.__hfLottie || []; window.__hfLottie.push(anim); /script.lottie-layer { width: 100%; height: 100%; }要点说明renderer: svg是 HyperFrames 合成中最常用的渲染器矢量保真且 DOM 可被截图path指向本地assets/下的 JSON 文件不要指向远程 URL原因见下文避免事项返回的anim对象lottie-web 的AnimationItem必须push进window.__hfLottie容器必须显式设置宽高通常为100%否则动画尺寸不稳定会影响合成布局。从源码看适配器对lottie-web的寻址方式是anim.goToAndStop(time * 1000, false)第一个参数为毫秒第二个参数false表示按时间而非帧号寻址以保证精度见 lottie.ts。时间会先经过Math.max(0, Number(ctx.time) || 0)归一化负时间被钳制为 0。暂停时调用anim.pause()。dotLottie 模式canvas 播放器lottiefiles/dotlottie-web是面向.lottie文件格式的 canvas 播放器接入方式如下canvas idproduct-lottie classlottie-canvas/canvas script srchttps://unpkg.com/lottiefiles/dotlottie-web/script script const player new DotLottie({ canvas: document.getElementById(product-lottie), src: assets/product-flow.lottie, autoplay: false, loop: false, }); window.__hfLottie window.__hfLottie || []; window.__hfLottie.push(player); /script.lottie-canvas { width: 100%; height: 100%; display: block; }dotLottie 播放器没有goToAndStop这样的统一寻址 API因此适配器按播放器形态分派见 lottie.tsdotLottie-web v2调用setCurrentRawFrameValue(frame)直接设置原始帧号帧号由time * frameRate计算并钳制到totalFrames - 1以内避免超出末帧dotLottie-web v1调用seek(percentage)百分比由(time / duration) * 100计算并钳制到 100当duration尚未就绪为 0 或非有限值时跳过寻址等 duration 可用后下一个渲染周期自然生效。测试 lottie.test.ts 对上述行为有完整覆盖例如seek({ time: 2 })对 lottie-web 断言调用goToAndStop(2000, false)对 v2 播放器断言setCurrentRawFrameValue(30)time1、fps30当frame 300超过totalFrames 60时断言钳制为59对 v1 播放器断言duration 2时seek依次收到[50], [0], [100]的百分比调用序列。多动画同步一个注册表同一时间点一个合成里可以同时出现多个 Lottie 动画背景、图标、装饰粒子等只需把每个实例都 push 进同一个window.__hfLottie数组window.__hfLottie window.__hfLottie || []; window.__hfLottie.push(backgroundAnim); window.__hfLottie.push(iconAnim); window.__hfLottie.push(confettiAnim);适配器的seek会遍历整个注册表并把所有实例拨到同一个合成时间点见 lottie.ts。单实例的寻址失败会被swallow捕获并跳过不会阻断其余实例——源码注释明确这是keep going for other instances的容错设计。另外适配器还提供**自动发现auto-discovery**能力即使合成代码没有手动 push只要页面上存在全局lottie对象即加载了 lottie.min.js适配器的discover()就会调用lottie.getRegisteredAnimations()读取所有已注册动画并去重合并进window.__hfLottie见 lottie.ts。不过契约仍然推荐显式注册——自动发现只是兜底显式注册不依赖库内部 API 的稳定性。组合时长data-duration为什么可以省略GSAP 合成的时间线对象会自动上报总时长而纯 Lottie 合成没有时间线对象渲染引擎必须知道合成总长度才能正确推进。适配器通过getInferredDurationSeconds()从注册实例直接读取原生时长见 lottie.tslottie-webtotalFrames / frameRate如 90 帧 30fps → 3 秒dotLottie优先使用播放器自身的duration字段缺失时回退到totalFrames / frameRate多实例取所有实例推断值的最大值Math.max因为合成长度必须容纳最长的动画未加载完成若totalFrames仍为 0资产尚未加载完返回null而非 0避免把仍在加载误判为真实时长为 0。运行时在 init.ts 的resolveAdapterDurationFloorSeconds()中汇总所有适配器的推断时长再与媒体时长下限、data-duration组合取最大值作为安全时长见 init.ts。因此只要每个动画都按契约注册到了window.__hfLottie即使不写data-duration、甚至设置loop: true运行时也能拿到有限时长来完成渲染——这正是原文档data-duration对 Lottie 合成是可选的这句话的底层依据。适用场景Good UsesAfter Effects 导出且已在 lottie-web 中确认渲染正确的资产Logo 揭示、图标循环、装饰点缀、产品 UI 动效把 Remotion 中的 Lottie 用法迁移为纯 HyperFrames HTML。避免事项Avoid原文档明确列出四类渲染期风险务必规避渲染时依赖远程pathURL——远程资源在渲染环境不可达会导致合成失败资产必须随项目本地化用play()启动播放——播放行为会破坏确定性一切由运行时 seek 接管假设不受支持的 After Effects 效果能原样导出——先在本机浏览器中打开 JSON 或.lottie文件实测确认异步加载播放器并在 HyperFrames 校验完页面之后才注册——注册太晚会错过适配器的发现与验证时机动画永远不会被寻址。验证lint 与 check编辑完 Lottie 合成后在项目根目录运行官方校验命令npx hyperframes lint npx hyperframes checklint用于静态检查合成结构资产路径、注册模式等check则进一步验证合成在渲染前的关键约束是否满足。两条命令的组合是提交或导出前的标准自检流程。源码路径速查适配器核心实现packages/core/src/runtime/adapters/lottie.tscreateLottieAdapter含discover/seek/pause/getInferredDurationSeconds时长自动推断的运行时折叠机制packages/core/src/runtime/init.tsresolveAdapterDurationFloorSeconds全局注册点与 lottie 全局对象的类型声明packages/core/src/runtime/window.d.ts适配器行为测试packages/core/src/runtime/adapters/lottie.test.ts寻址、钳制、时长推断、自动发现去重均有断言适配器选型总览skills/hyperframes-animation/SKILL.md外部库参考lottie-webAirbnb 的 bodymovin 库的loadAnimation选项以及 LottieFiles 官方 dotLottie web 播放器方法文档均可在各自官方文档站查阅本文不再赘述。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考