# @aarsteinmedia/dotlottie-player 中文文档

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

版本：6\.6\.8
npm 元数据更新时间：2026-11-02T20:26:35.240Z
中文译文更新时间：2026-11-05T21:28:57.012Z
软件包许可：GPL-2\.0-or-later

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

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

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

- 包体积（解压后）：1.4 MB，23 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@types/react \>= 16\.0\.0
- 首次发布：2023-09-17T10:27:50.610Z
- 最新版本发布：2026-11-02T20:26:35.058Z
- 近 30 天下载量：17805（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：185（近 12 个月 47 个）

## 中文简介

在您的网络应用程序中播放乐天动画的 Web 组件 .

## 安装

```sh
npm install @aarsteinmedia/dotlottie-player
```

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

## README

# AM Lottie 显示器

![Awesome Vector Animations](https://npmcn.com/.github/readmeBanner.svg)

我们自豪地宣称,这是Lottie Player网络组件中最多能、最轻能、最有效率的。 它与服务器侧渲染和完全框架-可知性兼容.

### 选择建筑

| 导入 | 什么时候用 |
| --- | --- |
| `@aarsteinmedia/dotlottie-player` | 完全播放器: 所有渲染器, [表达式](https://helpx.adobe.com/after-effects/using/expression-basics.html), SVG 效应,加上在苍蝇上转换/压缩. |
| `@aarsteinmedia/dotlottie-player/svg` | 带有表达式和SVG效果的SVG渲染器,但不进行转换/压缩. 当您需要这些特性时使用此功能, 但不想要装入完整的构件 . |
| `@aarsteinmedia/dotlottie-player/canvas` | Canvas 渲染器 – 通常在硬件上比较容易,大多数动画的视觉效果都与SVG相类似. 大部分SVG特有效果都没有. |
| `@aarsteinmedia/dotlottie-player/light` | 最小的建筑:仅SVG,有表达和SVG效果被剥去. 没有转换/关闭. |

## 演示

这里 [演示](https://www.aarstein.media/en/dotlottie-player),在 Next.js 上运行,并带有 TypeScript .

## 安装

### 在 HTML 中

-   从 CDN 导入 :
    
    -   满:
        
        ```html
        <script src="https://unpkg.com/@aarsteinmedia/dotlottie-player@latest/dist/unpkg-full.js"></script>
        ```
        
    -   SVG : (英语)
        
        ```html
        <script src="https://unpkg.com/@aarsteinmedia/dotlottie-player@latest/dist/unpkg-svg.js"></script>
        ```
        
    -   帆布:
        
        ```html
        <script src="https://unpkg.com/@aarsteinmedia/dotlottie-player@latest/dist/unpkg-canvas.js"></script>
        ```
        
    -   光线 :
        
        ```html
        <script src="https://unpkg.com/@aarsteinmedia/dotlottie-player@latest/dist/unpkg-light.js"></script>
        ```
        
-   从 `node_modules` 同样的方式,例如. `/node_modules/@aarsteinmedia/dotlottie-player/dist/unpkg-full.js`。 。 。 .
    

### 在 Java 脚本或类型脚本中

1.  使用 npm 、 pnpm 或纱线安装 :
    
    ```bash
    pnpm add @aarsteinmedia/dotlottie-player
    ```
    
2.  导入您的应用程序( 选择一个构件 ) :
    
    ```js
    import '@aarsteinmedia/dotlottie-player'
    // or:
    import '@aarsteinmedia/dotlottie-player/svg'
    import '@aarsteinmedia/dotlottie-player/canvas'
    import '@aarsteinmedia/dotlottie-player/light'
    ```
    

因为这是一个Web组件, 你把它添加到你的Web应用程序的全球范围。 与模块化组件不同,它只应该导入一次 — — 最好是在应用程序生命周期的早期.

如果您正在使用 TypeScript 并想要导入组件类型, 请在全局导入之外进行模块化 :

```ts
import '@aarsteinmedia/dotlottie-player' // Do this once globally.
import type DotLottiePlayer from '@aarsteinmedia/dotlottie-player' // Do this per file that needs the type.
```

⚠️ 注意,这种模式可能引起穿插错误,例如: `import/no-duplicates`。 。 。 .

## 使用量

添加数据 `dotlottie-player` 标出和标出 `src` 给您选择的洛蒂动画:

```html
<dotlottie-player
  autoplay
  controls
  subframe
  loop
  id="find-me"
  src="https://storage.googleapis.com/aarsteinmedia/am.lottie"
  style="width: 320px; margin: auto;"
>
</dotlottie-player>
```

### 装入动画

要设定动画程序,请使用 `load()` 方法.

```javascript
const player = document.querySelector('#find-me')
await player?.load('https://storage.googleapis.com/aarsteinmedia/am.lottie')
```

### 转换为点Lottie

_(仅可入建_

如果您有一款Lottie JSON动画,并想将其转换成"点Lottie"文件——以杠杆压缩,组合多款动画,并维护一个整齐的文件库——您可以使用此功能 `convert()` 方法。 这将触发浏览器下载 .

若为 `controls` 在右侧的上下文菜单中也有一个转换按钮.

### 转换为 JSON

_(仅可入建_

如果您正在调试 Dot Lottie 动画( 例如, 表达式没有如预期的那样有效), 您可以使用 `convert()` 方法或通过转换按钮,如果 `controls` 已启用.

### 组合动画

_(仅可入建_

将多个动画合并到单个点Lottie文件中,请使用 `addAnimation()` 方法。 这也触发了浏览器的下载. 源文件可以是dot Lottie或JSON,输出将永远是dot Lottie:

```javascript
const player = document.querySelector('#find-me')
await player?.addAnimation([
  { id: 'animation_1', url: '/url/to/animation_1.lottie' },
  { id: 'animation_2', url: '/url/to/animation_2.json', direction: -1, speed: 2 }
])
```

您也可以使用这种方法而无需任何 `<dotlottie-player>` 在页面上。 只要剧本上膛, `dotLottiePlayer()` 作为全球方法可供使用.

```js
await dotLottiePlayer().addAnimation([
  { id: 'animation_1', url: '/path/to/animation_1.lottie' },
  { id: 'animation_2', url: '/path/to/animation_2.json', direction: -1, speed: 2 }
])
```

新文件初始化后会自动加载第一部动画. 您可以使用 : `next()` 财务报告和审定财务报表 `prev()` 方法,或控件中的导航按钮.

以下是如何控制多个动画的回放设置:

```html
<dotlottie-player
  subframe
  id="find-me"
  src="/path/to/combined-animations.lottie"
>
</dotlottie-player>
```

```js
const player = document.querySelector('#find-me')
player?.setMultiAnimationSettings([
  {
    autoplay: true
  },
  {
    autoplay: true,
    loop: true
  }
])
```

### 角质

1.  导入组件为 `app.component.ts`。 。 。 .

```ts
import { Component } from '@angular/core'
import '@aarsteinmedia/dotlottie-player'

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  title = 'your-app-name'
}
```

2.  将玩家添加到您的 HTML 模板中 .

### React.js / Next.js (英语)

因为这是Web组件而不是反应组件,请注意,您必须使用 `class` 属性( 不) `className`在分配CSS课程时.

如果您更喜欢纯反应逻辑, 您可能想要查看 [@aarsteinmedia/dotlotie-反应](https://www.npmjs.com/package/@aarsteinmedia/dotlottie-react)。 。 。 .

```jsx
import '@aarsteinmedia/dotlottie-player'

function App() {
  return (
    <dotlottie-player
      autoplay
      controls
      loop
      class="your-class-name"
      src="https://storage.googleapis.com/aarsteinmedia/am.lottie"
      style={{
        width: '320px',
        margin: 'auto'
      }}
    />
  )
}

export default App
```

如果您正在使用 TypeScript 并想要指定一个 `ref`像这样

```tsx
import { useRef } from 'react'
import '@aarsteinmedia/dotlottie-player'
import type DotLottiePlayer from '@aarsteinmedia/dotlottie-player'

function App() {
  const animation = useRef<DotLottiePlayer | null>(null)
  return (
    <dotlottie-player
      subframe
      ref={animation}
      src="https://storage.googleapis.com/aarsteinmedia/am.lottie"
    />
  )
}

export default App
```

### Vue.js / Nuxt.js (使用vite.js) 互联网档案馆的存檔,存档日期2013-12-02

1.  宣布: `dotlottie-player` 标记为自定义元素, 因此 Vue 不试图将其作为 Vue 组件解决 .

#### 在Vue.js语中

`vite.config.ts`数字 :

```ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag: string) => tag === 'dotlottie-player',
        }
      }
    })
  ]
})
```

#### 在 Nuxt.js 中

`nuxt.config.ts`数字 :

```ts
export default defineNuxtConfig({
  vue: {
    compilerOptions: {
      isCustomElement: (tag: string) => tag === 'dotlottie-player',
    }
  }
})
```

2.  将包导入一次以获取其副作用(注册自定义元素) .

#### 在Vue.js语中

`main.ts`数字 :

```ts
import { createApp } from 'vue'
import '@aarsteinmedia/dotlottie-player'
import App from './App.vue'

createApp(App).mount('#app')
```

#### 在 Nuxt.js 中

创建一个 `plugins` 如果此文件夹不存在,则在根中添加一个客户端插件,例如:. `dotlottie-player.client.ts`数字 :

```ts
import '@aarsteinmedia/dotlottie-player'

export default defineNuxtPlugin(() => {})
```

3.  使用模板中的元素 :

```vue
<template>
  <dotlottie-player
    src="https://storage.googleapis.com/aarsteinmedia/am.lottie"
    autoplay
    controls
    subframe
    loop
    style="width: 320px; margin: auto;"
  />
</template>
```

## 属性

| 属性/ 属性 | 说明 | 类型 | 默认 |
| --- | --- | --- | --- |
| `animateOnScroll` | 以卷行为活. | `boolean` | `false` |
| `autoplay` | 装入时播放动画. | `boolean` | `false` |
| `background` | 背景颜色 . | `string` | `transparent` |
| `controls` | 显示控制. | `boolean` | `false` |
| `count` | 循环动画的次数. | `number` | `0` |
| `delay` | 延迟播放 OnVisible 游戏, 以毫秒计 . | `number` | `0` |
| `description` | 屏幕阅读器描述 . | `string` | `undefined` |
| `direction` | 动画的方向. | `1` | `-1` | `1` |
| `dontFreezeOnBlur` | 当窗口失去焦点时, 禁用冻结播放( freze- on- blur 是默认的) . | `boolean` | `false` |
| `hover` | 是否在鼠标徘徊时播放 . | `boolean` | `false` |
| `intermission` | 在循环迭接之间暂停, 以毫秒计 . | `number` | `0` |
| `loop` | 是否循环动画 . | `boolean` | `false` |
| `mode` | 游戏模式. | `normal` | `bounce` | `normal` |
| `mouseout` | 启动鼠标出局. | `void` | `stop` | `pause` | `reverse` | `stop` |
| `objectfit` | 在容器中调整动画大小 . | `contain` | `cover` | `fill` | `none` | `scale-down` | `contain` |
| `once` | 如果播放 OnVisible 是真实的, 播放一次还是观看动画的任何时候 . | `boolean` | `false` |
| `playOnClick` | 是否在点击时切换播放 . | `boolean` | `false` |
| `playOnVisible` | 可见就玩. | `boolean` | `false` |
| `quiet` | 在关键负载错误上压制图形错误屏幕. | `boolean` | `false` |
| `renderer` | 要使用的渲染器( 只全建; 其他建置锁定此) . | `svg` | `canvas` | `html` | `svg` |
| `selector` | 通过 id 属性在被点击的元素上播放. | `string` | `undefined` |
| `simple` | 隐藏高级控件(loop,boomerang,转换,快照,设置). | `boolean` | `false` |
| `speed` | 动画速度. | `number` | `1` |
| `src` _(必须)_ | 给Lottie JSON的URL或"点"Lottie的URL. | `string` | `undefined` |
| `subframe` | 当启用时,这可以帮助减少一些动画的闪烁,特别是在Safari和iOS设备上. | `boolean` | `false` |

## 方法

| 方法 | 函数 |
| --- | --- |
| `addAnimation(params: AddAnimationParams) => Promise<Result>` | _(仅可入建_ 将动画合并到一个新的点Lottie文件并触发下载. |
| `convert(params: ConvertParams) => Promise<Result>` | _(仅可入建_ 在JSON和点洛蒂之间转换. 触发浏览器中的下载. |
| `destroy() => void` | 将动画化并去除DOM中的元素. |
| `getLottie() => AnimationItem | null` | 返回组件中使用的Lottie-web实例. |
| `getManifest() => LottieManifest | undefined` | 返回点 Lottie 列表,如果有的话. |
| `getMultiAnimationSettings() => AnimationSettings[]` | 返回多激活设置. |
| `getSegment() => [number, number] | undefined` | 返回当前播放段 . |
| `load(src: string) => Promise<void>` | 用 URL 或 JSON 字符串装入动画 . |
| `next() => void` | 下个动画( 如果在文件中有多个) . |
| `pause() => void` | 暂停. |
| `prev() => void` | 前作动画( 如果在文件中有多个) . |
| `play() => void` | 弹. |
| `reload() => Promise<void>` | 重载. |
| `seek(value: number | string) => void` | 去装帧。 可以是数字或百分比字符串(例如:. `50%`) (中文(简体) ). |
| `setCount(value: number) => void` | 动态设置环数. |
| `setDirection(value: 1 | -1) => void` | 设定方向. |
| `setLoop(value: boolean) => void` | 设定回路. |
| `setMultiAnimationSettings(value: AnimationSettings[]) => void` | 设置多动设置 . |
| `setSegment(value: [number, number]) => void` | 只播放动画的一部分. 例如,从框架10到框架60将是: `[10, 60]`。 。 。 . |
| `setSpeed(value?: number) => void` | 设定速度 . |
| `setSubframe(value: boolean) => void` | 设定子框 . |
| `snapshot(download?: boolean, name?: string) => string | null` | 抓取当前框架为 SVG 。 默认下载时间 `download` 这是真的. |
| `stop() => void` | 别说了. |
| `toggleBoomerang() => void` | 切换到 `bounce` 财务报告和审定财务报表 `normal`。 。 。 . |
| `toggleLoop() => void` | 切换循环. |
| `togglePlay() => void` | 切换游戏. |

## 活动

以下事件已曝光,可通过下列方式收听: `addEventListener` 打电话.

| 名称 | 说明 |
| --- | --- |
| `complete` | 动画完成 — 包括所有循环 |
| `destroyed` | 动画毁灭 |
| `error` | 源无法解析、 无法装入或格式出错 |
| `frame` | 输入新框架 |
| `freeze` | 动画因玩家出镜而暂停 |
| `load` | 动画已装入 |
| `loop` | 循环完成 |
| `next` | 在多动画文件中切换到下个动画 |
| `_play` | 动画已经开始播放 |
| `_pause` | 动画已暂停 |
| `previous` | 在多动画文件中切换到上一个动画 |
| `ready` | 动画已装入, 玩家已准备好 |
| `rendered` | 玩家 UI 已提供 |
| `stop` | 动画停止了 |

## 文字新闻插件

![](https://npmcn.com/.github/wpIcon.svg)

我们做了一个免费的WordPress插件,它与Gutenberg Blocks, Elementor, Divi Builder 和 Flatsome UX Builder 合作: [AM Lottie 显示器](https://www.aarstein.media/en/am-lottieplayer)。它具有这个软件包的所有功能,有一个有用的用户界面.

它的超轻量级——并且只在使用动画的页面上加载.

我们还制作了一个溢价WordPress插件,用于购买: [AM Lottie Player PRO 游戏软件](https://www.am-lottieplayer.com/)。它有一个易于使用的GUI,用于将多个Lottie动画合并到一个文件中并进行控制,将JSON转换为带有拖放功能的DotLottie,以及许多更独有的功能.

## 许可证

GPL-2.0-或-后期

## 常见问题

### @aarsteinmedia/dotlottie-player 是什么？

在您的网络应用程序中播放乐天动画的 Web 组件 \.

### 如何安装 @aarsteinmedia/dotlottie-player？

在项目目录运行 npm install @aarsteinmedia/dotlottie-player，或使用 pnpm add / yarn add / bun add。

### @aarsteinmedia/dotlottie-player 支持 TypeScript 吗？

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

### @aarsteinmedia/dotlottie-player 支持 ESM 还是 CommonJS？

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

### @aarsteinmedia/dotlottie-player 可以商用吗？

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

### @aarsteinmedia/dotlottie-player 的下载量有多少？

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

### @aarsteinmedia/dotlottie-player 还在维护吗？

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