dotLottie 文件结构与 manifest 解析

标准目录结构

把一个 .lottie 文件改后缀成 .zip 解压，你会看到：

my-animation.lottie (解压后)
├── manifest.json              # ★ 核心元数据文件
├── animations/
│   ├── normal.json            # 一段动画（标准 Bodymovin JSON）
│   ├── hover.json
│   ├── pressed.json
│   └── disabled.json
├── images/                    # 关联图片（如果动画用了位图）
│   └── background.png
├── fonts/                      # 字体文件（如果有文字图层）
│   └── Arial.ttf
├── themes/                     # 主题皮肤（可选）
│   ├── light.json
│   └── dark.json
└── state_machines/            # 状态机定义（可选）
    └── button-states.json

manifest.json 详解

manifest.json 是整个 dotLottie 文件的"目录索引"，播放器启动时第一时间读取它：

{
  "version": "1.0",
  "generator": "LottieFiles Creator",
  "createdAt": "2024-10-01T12:00:00Z",
  "animations": [
    {
      "id": "normal",
      "url": "animations/normal.json",
      "speed": 1,
      "duration": 2.5
    },
    {
      "id": "hover",
      "url": "animations/hover.json"
    },
    {
      "id": "pressed",
      "url": "animations/pressed.json"
    }
  ],
  "activeAnimationId": "normal",
  "stateMachine": {
    "url": "state_machines/button-states.json"
  },
  "themes": [
    {
      "id": "light",
      "url": "themes/light.json"
    },
    {
      "id": "dark",
      "url": "themes/dark.json"
    }
  ],
  "tokens": {
    "brand-primary": "#0066FF",
    "text-color": "#333333"
  }
}

关键字段

播放器怎么用 manifest

1. 加载 .lottie 文件（本质上是解压 ZIP）。
2. 读取 manifest.json。
3. 找到 activeAnimationId 指定的动画，加载对应的 JSON。
4. 如果有 stateMachine 字段，加载状态机定义。
5. 如果有 tokens 字段，初始化 Motion Tokens 默认值。
6. 开始渲染动画，等待状态机事件或 token 更新。

和原生 JSON 的对比

规范文档

dotLottie 规范开源在 dotlottie.io 官方网站，包含完整的 manifest schema、目录结构要求、状态机和主题皮肤的格式规范。