# @aarsteinmedia/lottie-web 中文文档

规范地址：https://npmcn.com/package/%40aarsteinmedia/lottie-web/

版本：1\.6\.9
npm 元数据更新时间：2026-11-02T20:14:04.218Z
中文译文更新时间：2026-11-05T22:13:38.191Z
软件包许可：GPL-2\.0-or-later

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aarsteinmedia/lottie-web
原文对照：https://npmcn.com/package/%40aarsteinmedia/lottie-web/?lang=original
项目主页：https://www.aarstein.media/en/dotlottie-player
源码仓库：https://github.com/aarsteinmedia/lottie-web

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：866 kB，25 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- peer 依赖：fflate ^0\.8\.3
- 首次发布：2025-03-24T08:30:01.827Z
- 最新版本发布：2026-11-02T20:14:04.043Z
- 近 30 天下载量：13593（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：105（近 12 个月 40 个）

## 中文简介

在浏览器中播放在 After Effect 中生成的动画

## 安装

```sh
npm install @aarsteinmedia/lottie-web
```

也可以使用：`pnpm add @aarsteinmedia/lottie-web`、`yarn add @aarsteinmedia/lottie-web`、`bun add @aarsteinmedia/lottie-web`

## README

# AM 乐天网

Airbnb 的脚本分叉 [乐天网](https://github.com/airbnb/lottie-web),为 [Aarstein 媒体点 Lottie 播放器生态系统](https://www.aarstein.media/en/dotlottie-player)。 。 。 .

## 为什么这个叉子存在

-   **更安全的表达方式** - 在效果表达式被评价后 `new Function` 改为 `eval`,这略微改善了安全和性能。 然而,对于不信任的投入, `/light` 建议.
-   **经济进口** – 这个软件包坚持模块化设计理念,提供颗粒导入,以免在应用程序中获得任何不需要的bloat — 只要你继续阅读.
-   **更好的相片渲染** – 虽然Canvas渲染不像SVG渲染那样多功能,但它更能表现并更有利于大多数浏览器处理视觉元素. 这个叉子有更好的DPR处理和更广泛的Canvas渲染器特性支持.
-   **方便安全部门改革** – 浏览器和Web API的用法为节点和服务器渲染而守护.
-   **更好的错误** ——失败通过打出的事件浮出水面,而不是沉默地失败.

此软件包主要是为 [`@aarsteinmedia/dotlottie-player`](https://www.npmjs.com/package/@aarsteinmedia/dotlottie-player) 财务报告和审定财务报表 [`@aarsteinmedia/dotlottie-react`](https://www.npmjs.com/package/@aarsteinmedia/dotlottie-react). 其他使用案例得到支持,但继承自上游Lottie-web行为.

## 安装

```bash
pnpm add @aarsteinmedia/lottie-web
```

如果您使用点Lottie的切入点,请同时安装对等依赖:

```bash
pnpm add fflate
```

## 入境点

在这里读这整件事都有好处。 还记得我说的模块设计吗? 就是这样.

| 导入 | 说明 |
| --- | --- |
| `@aarsteinmedia/lottie-web` | 完全构建: SVG + 画布渲染器,效果和表达式 |
| `@aarsteinmedia/lottie-web/light` | 只有 SVG 渲染器, 没有表达式 |
| `@aarsteinmedia/lottie-web/svg` | SVG 有表达式的渲染器 |
| `@aarsteinmedia/lottie-web/canvas` | 带有表达式的相机 |
| `@aarsteinmedia/lottie-web/utils` | 共享助手和词库 |
| `@aarsteinmedia/lottie-web/dotlottie` | dot Lottie 存档公用事业 |

## 基本用途

```ts
import lottie, { loadAnimation } from '@aarsteinmedia/lottie-web'
import type { AnimationItem } from '@aarsteinmedia/lottie-web'
import { PlayerEvent } from '@aarsteinmedia/lottie-web/utils'

const container = document.getElementById('animation')

const animation: AnimationItem = loadAnimation({
  container,
  renderer: 'svg',
  loop: true,
  autoplay: true,
  path: '/animations/hero.json',
})

animation.addEventListener(PlayerEvent.Complete, () => {
  console.log('Animation finished')
})

// Later
animation.destroy()
```

### 内置动画数据

```ts
import animationData from './animation.json'

const animation = loadAnimation({
  container: document.getElementById('animation'),
  renderer: 'svg',
  animationData,
  autoplay: false,
})
```

### SVG 唯一的捆绑( 小)

```ts
import lottie from '@aarsteinmedia/lottie-web/svg'
```

## 活动

`AnimationItem` 扩展小事件发射器。 共同活动包括:

| 活动 | 当它起火时 |
| --- | --- |
| `DOMLoaded` | 动画已经准备好播放了 |
| `enterFrame` | 每个框架 |
| `complete` | 回放到达尾端 |
| `loopComplete` | 循环迭代完成 |
| `configError` | 无效的配置或数据 |
| `renderFrameError` | 帧无法渲染 |
| `destroy` | 动画被撕了 |

导入事件名称 `@aarsteinmedia/lottie-web/utils`数字 :

```ts
import { PlayerEvent } from '@aarsteinmedia/lottie-web/utils'

animation.addEventListener(PlayerEvent.RenderFrameError, (event) => {
  console.error(event?.nativeError)
})
```

## 发展

```bash
pnpm install
pnpm dev        # preview player with live reload
pnpm lint       # eslint
pnpm test       # vitest
pnpm prod       # typecheck + production build
pnpm check      # lint, test, build, and verify version injection
```

`pnpm dev` 需要一个本地 `assets/` 样本目录 `.json` 编号 : `.lottie` 文件( 此回波跟踪一个同名链接到同名兄弟) `lottie-fixtures` 文件夹). 试验使用固定装置 `tests/lottie-fixtures/` 而不依赖 `assets/`。 。 。 .

## 许可证

GPL2.0-或后发. 如果你发行合并作品或衍生作品,请查看上游Lottie-web许可的影响.

## 常见问题

### @aarsteinmedia/lottie-web 是什么？

在浏览器中播放在 After Effect 中生成的动画

### 如何安装 @aarsteinmedia/lottie-web？

在项目目录运行 npm install @aarsteinmedia/lottie-web，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：fflate（^0\.8\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aarsteinmedia/lottie-web 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aarsteinmedia/lottie-web 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @aarsteinmedia/lottie-web 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aarsteinmedia/lottie-web 可以商用吗？

@aarsteinmedia/lottie-web 使用 GPL-2\.0-or-later 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以兼容的 GPL 许可开源。仅在内部使用、不对外分发时不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。

### @aarsteinmedia/lottie-web 的下载量有多少？

根据 npm 官方下载统计，@aarsteinmedia/lottie-web 在 2026/10/05 – 2026/11/03 这 30 天内被下载 13,593 次，日均约 453 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aarsteinmedia/lottie-web 还在维护吗？

最新版本 1\.6\.9 发布于 2026/11/03（3 天前）；至今共发布 105 个版本，其中过去 12 个月发布了 40 个；首次发布于 2025/03/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。