Rekapi 动画序列化实战如何用 exportTimeline 保存与恢复关键帧动画【免费下载链接】rekapiA keyframe animation library for JavaScript项目地址: https://gitcode.com/gh_mirrors/re/rekapiRekapi 是一款专为 JavaScript 打造的关键帧动画库而动画序列化正是它最实用也最容易被忽视的能力之一。通过 Rekapi 自带的exportTimeline与importTimeline方法你可以在几行代码内把整条关键帧动画导出为 JSON 数据、保存到本地或服务器再随时恢复并重放。本教程将带你完整掌握这套保存与恢复关键帧动画的实战流程零基础也能轻松上手。 为什么你需要动画序列化先想一个场景你精心编排了一段 10 秒的关键帧动画包含多个演员Actor、几十个关键帧和自定义缓动曲线。如果动画只存在于内存里那么一旦页面刷新、用户关闭浏览器或切换设备一切都要从头手动搭建。动画序列化Serialization就是把动画的完整配方转成纯文本数据JSON从而实现 本地持久化存入localStorage或 IndexedDB☁️ 云端同步上传到服务器跨设备恢复 内容复用同一段动画直接复制给其他页面或项目 素材交付设计师导出的动画数据前端直接播放Rekapi 的exportTimeline正是为这个场景而生它位于 src/rekapi.js 中实现非常轻量。 快速上手用 exportTimeline 导出动画先看一个最简单的例子。我们创建一个动画让一个方块在 2 秒内从左侧移动到右侧import { Rekapi, Actor } from rekapi; // 创建动画实例 const rekapi new Rekapi(); // 创建演员Actor const actor new Actor(); actor .keyframe(0, { x: 0 }) // 第 0msx 0 .keyframe(1000, { x: 200 }) // 第 1000msx 200 .keyframe(2000, { x: 0 }); // 第 2000msx 0回到起点 rekapi.addActor(actor); // 一键导出整条时间线 const timelineData rekapi.exportTimeline();就这么简单exportTimeline()返回的是一个可直接被JSON.stringify序列化的普通对象你立刻就能保存// 保存到 localStorage localStorage.setItem(myAnimation, JSON.stringify(timelineData)); // 或者发送到服务器 await fetch(/api/animations, { method: POST, body: JSON.stringify(timelineData) }); 关键点exportTimeline输出的不是动画帧图片而是数据配方——体积极小通常几 KB却包含重建整段动画所需的全部信息。 读懂导出的数据结构导出的对象包含三大部分对应 src/main.js 中定义的timelineData类型{ duration: 2000, actors: [ { start: 0, end: 2000, trackNames: [x], propertyTracks: { x: [ { millisecond: 0, name: x, value: 0, easing: linear }, { millisecond: 1000, name: x, value: 200, easing: linear }, { millisecond: 2000, name: x, value: 0, easing: linear } ] } } ], curves: {} }各字段的含义如下字段含义duration动画总时长毫秒actors所有演员的数组每个演员包含起止时间、属性轨道propertyTrackspropertyTracks每个属性如x、opacity对应的关键帧列表curves动画中用到的自定义贝塞尔缓动曲线定义每个关键帧propertyData都记录了millisecond时间点、name属性名、value值和easing缓动方式这些字段的定义见 src/main.js 和 src/keyframe-property.js。 用 importTimeline 一键恢复关键帧动画保存只是第一步恢复才是关键。importTimeline的作用恰好相反读取导出的数据自动创建所有 Actor、关键帧和自定义缓动曲线。// 从 localStorage 读取 const savedData JSON.parse(localStorage.getItem(myAnimation)); // 新建一个 Rekapi 实例并导入 const newRekapi new Rekapi(); newRekapi.importTimeline(savedData); // 直接播放动画完全还原 newRekapi.play();这段代码背后的逻辑非常优雅看 src/rekapi.js 的实现就知道importTimeline会先遍历curves用setBezierFunction恢复所有自定义缓动曲线再为每个 actor 数据创建新的Actor并通过addActor加入动画。在 test/rekapi.js 的测试中官方验证了导出再导入后再次导出得到完全一致的数据这一往返一致性所以你可以放心大胆地使用。 完整实战搭建一个动画保存与恢复系统把前面学到的串起来我们来写一个完整的实战示例让动画在用户离开页面时自动保存回来时自动恢复。import { Rekapi, Actor } from rekapi; const STORAGE_KEY rekapi_demo_animation; let rekapi new Rekapi(); // 创建演员 const actor new Actor(); actor .keyframe(0, { x: 0, opacity: 1 }) .keyframe(1000, { x: 300, opacity: 0.5 }, easeOutQuad) .keyframe(2000, { x: 0, opacity: 1 }); rekapi.addActor(actor); // ① 保存动画 function saveAnimation() { const data rekapi.exportTimeline(); localStorage.setItem(STORAGE_KEY, JSON.stringify(data)); console.log(✅ 动画已保存时长, data.duration, ms); } // ② 恢复动画 function restoreAnimation() { const saved localStorage.getItem(STORAGE_KEY); if (!saved) return false; rekapi new Rekapi(); rekapi.importTimeline(JSON.parse(saved)); console.log(✅ 动画已恢复); return true; } // ③ 绑定生命周期离开页面保存返回页面恢复 window.addEventListener(beforeunload, saveAnimation); if (!restoreAnimation()) { // 没有历史数据从头播放 rekapi.play(); } else { // 恢复后从上次的位置继续播放 rekapi.playFromCurrent(); }这个小系统实现了完整的保存关键帧动画 → 持久化 → 恢复重放闭环非常适合游戏存档、H5 交互动画、可视化编辑器等场景。⚙️ 进阶技巧withId 选项与自定义缓动曲线1. 保留内部 IDexportTimeline({ withId: true })默认情况下导出数据不包含内部id字段这让数据更干净、体积更小。但如果你需要在恢复后精确追踪某个 Actor 或关键帧比如编辑器场景可以开启withIdconst data rekapi.exportTimeline({ withId: true }); // actors[0].id 和 propertyTracks.x[0].id 都会被保留这一选项在 src/rekapi.js 中传入最终由 src/actor.js 和 src/keyframe-property.js 执行。恢复后你就能通过getActor(id)精准操作特定演员。2. 自定义缓动曲线自动跟随导出使用 Shifty 注册的自定义贝塞尔曲线会被exportTimeline自动收集到curves字段中见 src/rekapi.jsimport { setBezierFunction } from shifty; // 注册一条自定义缓动曲线 setBezierFunction(bounceIn, 0.5, -0.5, 0.75, 1.3); actor.keyframe(0, { y: 0 }); actor.keyframe(500, { y: -100 }, bounceIn); const data rekapi.exportTimeline(); console.log(data.curves.bounceIn); // { displayName: bounceIn, x1: 0.5, y1: -0.5, x2: 0.75, y2: 1.3 }导入时importTimeline会自动用这些控制点重建曲线动画效果分毫不差。测试 test/rekapi.js 也专门验证了这个特性。⚠️ 新手常见误区与注意事项函数关键帧不会被序列化exportTimeline导出的数据是纯 JSON 友好的如果关键帧值是函数它无法被序列化。这类逻辑请在恢复后手动重新绑定。导出前先addActor确保演员都已加入 Rekapi 实例再导出否则actors数组会为空。导入会新增演员importTimeline不会清空现有演员如果需要在全新实例中恢复请使用new Rekapi()。渲染上下文需要自行处理导出的数据不含渲染配置恢复动画后记得重新设置渲染器Canvas 或 DOM。 总结通过本教程你已经学会了 Rekapi 动画序列化的完整链路exportTimeline()一键导出 JSON 格式的关键帧动画数据src/rekapi.jsimportTimeline()从数据完整重建动画src/rekapi.js配合localStorage或服务器实现动画的保存与恢复用withId: true保留追踪 ID自定义缓动曲线自动随导出携带动画序列化让 Rekapi 的关键帧动画不再是一次性的——你可以像保存文档一样保存动画在任何地方重新播放。现在就打开你的项目试试用exportTimeline把第一段动画保存下来吧【免费下载链接】rekapiA keyframe animation library for JavaScript项目地址: https://gitcode.com/gh_mirrors/re/rekapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考