mcpField
L
lottie-animation-delivery

lottie-animation-delivery

github.com/calesthio设计与 UI219103 次安装15 周前更新
代码仓库

关于 lottie-animation-delivery

此制作技能帮助团队将 Lottie 矢量动画交付到目标播放器和平台，涵盖兼容性检查、导出选择、资源处理与播放验证。

主要功能

  1. 01规划目标播放器兼容性矩阵
  2. 02准备 After Effects 导出
  3. 03选择字形或运行时文本
  4. 04打包 JSON 或 dotLottie 资源
  5. 05验证播放与帧捕获

适用场景

  1. 01检查动画功能与目标播放器的兼容性
  2. 02准备本地化动画文本和字体
  3. 03为多个播放器打包资源
  4. 04为视频捕获确定性动画帧

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/calesthio/generative-media-skills --skill lottie-animation-delivery

安装后在 Claude Code 中输入/lottie-animation-delivery确认已加载。

附带文件EVAL.md

详细介绍

Lottie 动画交付

当设计好的矢量动画需要从创作工具可靠地交付到 Web、移动端、应用程序或渲染视频播放器时，使用此技能。生产中的难点在于互操作：在功能支持各不相同的实现中，保留预期的动作、字体排版、素材、时序、无障碍支持和控制方式。

Lottie 不是通用的 After Effects 渲染器。在动画定稿前，就应将目标播放器矩阵作为输入，而不是只在导出后进行测试。

依据与变动性

  • 文档说明的事实： 来自官方 Lottie 规范、lottie-web、dotLottie 规范、W3C 或浏览器文档的行为。
  • 生产经验法则： 实用的默认方案，必须针对目标播放器和设计进行测试。
  • 实证观察： 从导出文件、播放器测试样例、设备、帧捕获或最终交付中测得的结果。

事实核查截至 2026-07-12。官方 Lottie 规范说明其仍在持续编写中。播放器功能支持、导出器选项、dotLottie 版本、状态机、主题和软件包 API 都可能发生变化。请记录确切的导出器和播放器版本，并重新查阅当前文档。

判断 Lottie 是否适用

当交付内容需要以下特性时，使用 Lottie：

  • 紧凑且可缩放的矢量动画；
  • 目标播放器支持的创作关键帧、形状、预合成、图像、文本、蒙版或轨道遮罩；
  • 运行时播放、拖动定位、标记、片段或状态变化；
  • 在多个受支持的播放器之间复用；
  • 响应式容器缩放；
  • 确定性地捕获帧并导入其他视频合成器。

以下情况请选择其他格式：

  • 实拍内容、视频图层、照片效果或像素处理占主导；
  • 音频属于动画素材约定的一部分；
  • 所需的 AE 功能无法在目标播放器中保留；
  • 离线渲染的精确度比运行时控制更重要；
  • 3D 摄像机、灯光、粒子、模拟或着色器行为超出已验证的播放器支持范围；
  • 使用简单的 CSS/SVG 过渡更易于维护。

文档说明的事实： 官方 lottie-web README 中的 AE Feature Support 部分指出，其 Bodymovin 导出器/播放器路径不支持视频、音频和图像序列。请将音频作为单独同步的媒体素材，在宿主合成中使用。

先确定交付矩阵

记录以下信息：

  • 源合成、尺寸、帧率、入点/出点范围以及已批准的参考渲染；
  • 目标播放器、版本、渲染器、浏览器/设备和宿主框架的确切信息；
  • JSON 或 .lottie 交付物，以及所需的 dotLottie 版本；
  • 自动播放、循环、片段、标记、速度、方向、状态和交互要求；
  • 文本策略：字形轮廓、运行时文本、本地化、字体、回退字体和授权；
  • 外部/嵌入式图像，以及 CORS/离线限制；
  • 使用到的蒙版、轨道遮罩、混合模式、效果、表达式、时间重映射和嵌套合成；
  • 响应式适配/裁剪行为，以及减少动态效果/静态回退方案；
  • 确定性视频捕获要求；
  • 文件大小、启动时间、内存和交付限制；
  • 所有权、源图稿权利、字体、图像、徽标和第三方声明。

在创作大量动画前，针对每项高风险功能创建一个最小功能测试样例，并在每个目标环境中进行测试。

了解交换模型

**文档所述事实：**Lottie 文档是一个根对象为 Animation 的 JSON。Animation 数据包括尺寸、帧率、入点/出点、图层、资源和动画属性。关键帧按帧排序，可使用保持或三次贝塞尔缓动。图层可以设置父子关系，使子图层变换与父图层变换组合。

因此，Lottie 适用于可按时间定位的矢量动画，但文档有效并不能证明所有播放器的渲染结果完全一致。规范涵盖的是生态中不断扩展的一部分，各播放器可能实现额外、缺失或不同的行为。

维护兼容性记录：

feature | source usage | web-svg | web-canvas | ios | android | dotlottie-player | fallback

填入针对锁定版本测试所得的结果。不要将通用支持表照搬到生产审批中。

制作与导出约定

Bodymovin/lottie-web 通常会将受支持的 After Effects 合成导出为 JSON。导出前：

  • 设置准确的合成尺寸、fps、工作区间和最终时长；
  • 删除未使用的图层、效果、表达式、关键帧以及尺寸过大的隐藏图稿；
  • 为图层和标记设置稳定且有语义的名称；
  • 仅在获得设计审批后，才转换或简化不受支持的效果；
  • 保留参考影片和有代表性的源帧；
  • 收集字体或将字体转为轮廓，并冻结已批准的文案；
  • 确定栅格资源使用外部文件、嵌入还是打包；
  • 保留可编辑的源文件和导出设置。

**lottie-web 文档所述事实：**Bodymovin 支持常见形状、预合成、纯色、图像、空对象、文本、蒙版和时间重映射，但存在局限。其合成选项包括将文本转换为字形形状；在存在引用时包含隐藏/引导图层；导出额外的合成；以及保留原始栅格资源名称。包含隐藏和引导图层会增大输出。

使用导出器的报告/预览，并对目标播放器进行测试。导出器预览无误，并不代表通过了跨平台验证。

字体排印：字形还是运行时文本

字形轮廓

文案固定且需要精确的视觉形状时，选择转换为字形。这样可以避免将运行时字体加载作为渲染依赖，但会增加矢量数据，失去正常的文本语义和可编辑性，并且文案或本地化内容变更时需要重新导出。

运行时文本和字体

需要本地化或动态文案，且目标播放器支持所需文本行为时，选择运行时文本。在动画初始化之前打包或预加载已获授权的字体；在每个播放器中测试字形塑形、换行、回退字体、字形覆盖范围、从右向左书写的文字、组合附加符号以及不同地区的文本扩展。

不要假设拉丁文字样例就能验证阿拉伯文、天城文、CJK 或其他文字。需要保持可访问性或支持动态翻译的文案，不要转换为轮廓，除非在宿主中提供等效的语义文本图层。

文本决策记录：

  • 准确的源字符串和语言地区；
  • 字体系列/文件/字重/样式/许可证/校验和；
  • 字形或文本模式；
  • 预期的换行框和换行位置；
  • 使用时的运行时替换 API；
  • 辅助功能文本和本地化负责人；
  • 字体加载或字形塑形失败时的回退方案。

图像、蒙版、轨道遮罩、效果和表达式

清点所有非形状功能。测试功能组合，而不只是孤立功能。

图像
  • 固定本地图像文件，并保留宽高比行为。
  • 最终包中避免使用可变的远程 URL。
  • 测试缺失/错误状态和离线使用情形。
  • 打包多个动画时，对共享资源去重。
  • 记录图像权利和变换操作。
蒙版和轨道遮罩

不同渲染器/播放器对蒙版和轨道遮罩的处理可能有所不同。测试边缘质量、反转/相减行为、嵌套、Alpha、裁剪和性能。如果目标播放器无法正确处理，可简化构造，将其转换为受支持的矢量几何图形，预渲染该元素，或更改交付格式。

效果和混合模式

不要假设 AE 效果或混合模式有可移植的等效实现。只使用目标矩阵中已验证的子集。将结果与参考帧进行比较，测试浅色、深色、透明和真实宿主背景。

表达式

表达式会增加可移植性和确定性方面的风险。lottie-web 提供了可禁用表达式的渲染器设置。必须使用表达式时：

  • 测试播放器的具体支持情况；
  • 避免依赖网络、墙上时钟、设备或未设种子的随机数；
  • 分析运行时开销；
  • 记录烘焙关键帧的回退方案；
  • 验证任意位置跳转。

有意选择 JSON 或 dotLottie

原始 Lottie JSON 可以单独引用或嵌入部分图像／字体资源。它简单且广为人知，但可能造成多文件管理问题。

**文档说明：**dotLottie 会将一个或多个 Lottie JSON 动画及资源打包为采用 Deflate 压缩的 ZIP 归档，扩展名为 .lottie。在 dotLottie v2 中，manifest.json 和 a/ 动画目录为必需项；i/、f/、t/ 和 s/ 可分别存放图像、字体、主题和状态机。清单必须包含版本和至少一个动画条目。

版本选择很重要。dotLottie 官方文档将 v2 标记为新项目的推荐版本，将 v1 标记为广泛支持的版本。选择主题或状态机等 v2 功能前，请验证目标播放器是否支持。

打包规则：

  • 根据实际文件验证清单 ID；
  • 确保文件名可移植且大小写一致；
  • 确保路径不会超出归档范围；
  • 仅包含必需资源；
  • 对共享图像／字体去重；
  • 记录初始动画／状态和可选主题；
  • 测试归档解析、资源缺失和不受支持的可选功能；
  • 保留原始 JSON／源包，以便调试和迁移。

除非记录转换过程并重新运行验证／参考比较，否则不要手动编辑生成的 JSON 或归档。

播放、标记和片段

**lottie-web 文档说明：**动画实例支持 play、pause、stop、速度、方向、goToAndStop、goToAndPlay、playSegments、setSubframe、getDuration 和 destroy 等控制操作。通过 isFrame 参数选择基于帧的跳转。setSubframe(false) 会遵循源合成的 fps；默认的子帧模式会以中间值更新。

使用标记作为稳定的语义编辑／状态名称，例如 idle、focus、success 和 reset。在每个播放器中验证具体名称、起始帧、时长、边界语义和回退行为。对于 dotLottie v2 状态机片段，规范指出缺失标记时会回退到整个动画范围；应将其视为验证缺陷，而非安全的默认行为。

测试：

  • 每个片段的第一帧和最后一帧；
  • 重复触发和中断；
  • 支持时的反向播放和速度变化；
  • 从每个有效状态出发的转换；
  • 无效／缺失标记的行为；
  • 循环边界是否出现重复帧卡顿；
  • 使用 destroy() 或目标播放器的等效操作进行清理。

如果含有 repeater 的同一个 animationData 对象被多次加载到 lottie-web 中，官方 README 建议每次加载都对其进行深度克隆，因为内部变更可能影响各个实例。

确定性视频捕获

对于按帧渲染的视频，请禁用自动播放，并在数据、DOM、字体和图像都准备就绪后显式跳转。

lottie-web 捕获示例：

const animation = lottie.loadAnimation({
  container,
  renderer: "svg",
  loop: false,
  autoplay: false,
  animationData,
});

await readyForCapture(animation, fonts, assets);
animation.setSubframe(false);

export function renderFrame(frame) {
  animation.goToAndStop(frame, true);
}

就绪辅助函数因宿主环境而异。请监听并验证相关的数据、DOM 和图像就绪事件以及字体 Promise；不要依赖固定延迟。

捕获要求：

  • 记录预期的源帧数和帧率；
  • 捕获前显式跳转到第 0 帧；
  • 使用固定的动画数据和本地资源；
  • 不使用自动播放、墙上时钟回调、未设种子的表达式或交互状态；
  • 测试孤立、反向和乱序跳转；
  • 固定渲染器和播放器版本；
  • 比较重复渲染的帧；
  • 基于宿主时间线单独同步音频。

根据契约决定是否使用子帧。源帧捕获通常使用 setSubframe(false)。如果宿主输出帧率不同且需要中间帧渲染，请明确测试所选的插值和帧映射，不要假设它们能保留时间信息。

响应式尺寸和变体

lottie-web 渲染器设置为 SVG 和 Canvas 提供 preserveAspectRatio 行为选项。请决定每个画布应采用 meet、slice，还是使用单独制作的合成。

  • meet 会保留整个画板，但可能出现黑边。
  • slice 会填满容器，但可能裁掉重要内容。
  • 只更改容器尺寸并不能重新设计字体、手势、安全区域或信息密度。

对于宽高比差异较大的情况，如果裁切规则无法保留信息，请制作单独的布局或源合成。请按最终尺寸测试线条粗细、小字号文字、蒙版、滤镜边界和栅格资源。

优化

在确认视觉效果正确且兼容目标环境后，再进行优化：

  • 移除未使用的图层和关键帧；
  • 在保留轮廓和缓动效果的前提下减少路径点；
  • 若有更精简的构造方案，请避免使用巨大的蒙版形状；
  • 降低嵌套复杂度和表达式计算量；
  • 根据实际文案和语言区域组合选择字形或字体；
  • 集中管理共用的 dotLottie 资源；
  • 压缩传输内容，但不要破坏归档格式的预期要求；
  • 针对 SVG、Canvas 或其他目标渲染器进行性能分析，不要笼统地宣称某一种始终最快。

测量包大小、解析和加载时间、首帧渲染时间、稳定播放性能、内存占用和销毁情况。如果产品需要，还应在低端目标设备和多个同时运行的实例上进行测试。

无障碍和安全

对于交互界面：

  • 在宿主控件或容器级别公开语义用途；
  • 确保按钮和状态变化无需依赖动画 DOM 也能操作；
  • 提供无障碍名称和描述，或相邻文本；
  • 遵循 (prefers-reduced-motion: reduce)，方法包括禁用自动播放、减少运动、选择平缓片段或显示静态海报；
  • 在需要时提供用户暂停或停止控件；
  • 绝不要只通过运动或颜色传达重要状态。

lottie-web 支持 SVG 渲染器设置中的标题和描述，但这不能替代宿主环境的无障碍语义，也不能替代 Canvas 或其他播放器的回退方案。

对于预录制导出，如有需要，请渲染减少动态效果的变体；CSS 无法更改已编码进视频的像素。

已记录事实： WCAG 2.2 SC 2.3.1 限制每秒闪烁超过 3 次的内容，低于阈值的情况除外。请在循环播放和最大预期显示尺寸下测试循环内容。SC 2.3.3 指出，除非交互触发的动态效果不可或缺，否则应允许用户关闭非必要的动态效果。

权利与来源

lottie-web 采用 MIT 许可证。该许可证不涵盖源图稿、After Effects 项目、字体、徽标、图像、插件、角色或下载的动画文件。文件在技术上可编辑或可公开查看，并不能证明拥有商业使用权。

请保留：

  • 动画／源文件所有者及许可证；
  • 导出器和播放器的版本／许可证；
  • 字体和图像许可证；
  • 资源校验和；
  • 修改和优化步骤；
  • 参考渲染及审批记录；
  • 分发目标和限制；
  • 适用时的生成媒体来源信息。

保留所需的声明，并将不明确的市场素材、模板、品牌、肖像或衍生作品权利问题上报处理。

验证与 QA

分层验证：

  1. 源文件： 已批准的参考版本、尺寸、fps、工作区间、准确文案和资源清单。
  2. 结构： JSON／架构或 dotLottie 清单／归档完整性、路径、ID、资源和版本。
  3. 功能对等性： 将源文件功能清单与每个目标播放器／渲染器进行对照。
  4. 帧对等性： 对比具有代表性的首帧／中间帧／末帧，以及遮罩、文本、效果和片段边界帧。
  5. 行为： 自动播放、循环、标记、片段、状态转换、无效状态以及销毁／重新加载。
  6. 排版： 字体加载、字形覆盖、文本塑形、换行、本地化和无障碍文本。
  7. 性能： 加载、播放、内存、同时运行的实例数和资源清理。
  8. 无障碍： 语义、减少动态效果、闪烁、控件以及静态／结构化替代方案。
  9. 捕获： 在宿主环境中检查帧数、任意跳转、重复帧、Alpha／背景以及音频同步。

严重问题包括：资源缺失、文案／字体错误、不受支持的功能导致含义改变、帧捕获不确定、片段／状态回退失效、不安全的闪烁、未按要求处理减少动态效果，或权利未经核实。

交付移交

请提供：

  • 可编辑的源文件和已批准的参考渲染；
  • 导出的 JSON 及资源和／或 .lottie 包；
  • 经过测试的版本对应的目标兼容性矩阵；
  • 准确的播放器初始化和生命周期说明；
  • 标记／片段／状态／主题文档；
  • 字体／图像包及许可证；
  • 减少动态效果／静态回退方案；
  • 验证和性能报告；
  • 相关的确定性捕获说明；
  • 来源记录、声明和已知限制。

示例 1：本地化引导流程

这是一个完整示例，而非强制套用的公式。

**意图：**为 Web、iOS 和 Android 提供包含三种状态（idle、scan、success）的引导插画，支持 6 种语言环境。

**约束：**动态本地化标签；无音频；320x320 逻辑画板；由宿主按钮提供交互语义；支持减少动态效果模式；一张小型栅格纹理；支持离线使用。

工作流：

  1. 在最终制作动画前，先在固定版本的目标播放器中测试形状、遮罩、文本和栅格素材。
  2. 将本地化标签保留为运行时文本；打包获得许可的字体，并在播放器初始化前测试所有语言环境的字形塑造和字形覆盖情况。
  3. 添加语义标记，并在所有目标平台中验证精确的片段边界。
  4. 优先打包 JSON/素材以确保广泛兼容；仅对通过所选版本/功能验证的目标平台添加 dotLottie 包。
  5. 由宿主控制状态和无障碍功能；Lottie 仅渲染视觉反馈。
  6. 导出后记录已批准的稳定 idle-poster 和 success-poster 标记帧。减少动态效果模式会直接跳转到这些帧，并将扫描扫过效果替换为短暂的不透明度变化。
  7. 测试离线加载、错误的语言环境、缺失字体、标记拼写错误、重复成功/重置，以及销毁/重新加载。

**预期结果：**文本准确本地化、视觉状态一致、状态不只通过动画传达而导致无障碍问题，并且没有远程依赖。

**可能出现的问题：**字体初始化过晚；某种文字脚本塑形错误；标记边界不一致；移动端播放器无法渲染遮罩；离线时缺少栅格纹理；多次加载共用已被修改的数据。

**变体：**如果运行时文本无法通过跨播放器测试，则导出针对各语言环境的字形动画，同时在宿主 UI 中保留语义标签文本。

示例 2：渲染视频中的 Lottie 图层

这是一个完整示例，而非强制套用的公式。

**意图：**在 30 fps 产品视频中，将已批准的 8 秒矢量路线动画用作确定性叠加层。

**约束：**透明背景；与旁白精确逐帧对齐；在固定版本的无头浏览器中使用 SVG 渲染器；无交互；旁白/音乐分离；最终输出 1920x1080 和 1080x1920 两个版本。

工作流：

  1. 固定 JSON、图像、字体策略、播放器版本和已批准的参考内容。
  2. 禁用自动播放和循环；等待数据、DOM、图像和字体就绪。
  3. 明确设置源帧/子帧行为，并将宿主帧映射到动画帧。
  4. 使用 goToAndStop(..., true) 跳转到每个所需帧；通过宿主合成器捕获 Alpha 通道。
  5. 渲染第 0 帧、第 1 帧、每个标记边界帧、遮罩/效果压力测试帧和最终帧各两次，并包含倒序渲染。
  6. 如果 slice 会裁切路线标签，则制作单独的竖屏布局。
  7. 在宿主时间线上混合音频；不要指望 Lottie 承载音频。
  8. 销毁实例，并验证多个工作线程任务之间不会累积 DOM/监听器/资源。

**预期结果：**在锁定的浏览器环境中反复渲染均得到相同帧，Alpha 通道正确，旁白提示精确，横屏/竖屏传达的信息一致。

**可能出现的问题：**固定延迟就绪检测漏掉图像；源帧/输出帧速率映射偏差一帧；自动播放在捕获前推进；远程字体导致换行变化；竖屏裁切截断标签；最终循环帧与首帧重复。

**变体：**如果目标渲染器无法重现所需的遮罩，则将已批准的 Lottie 图层预渲染为无损 Alpha 序列，并说明交互式素材和视频衍生版本采用不同的交付路径。

资料来源

已核查的官方和权威资料（2026-07-12）：

评论

支持 Markdown