# @dotlottie/react-player 中文文档

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

版本：1\.6\.19
npm 元数据更新时间：2026-09-02T04:43:50.347Z
中文译文更新时间：2026-11-12T17:27:05.380Z
软件包许可：MIT

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

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

弃用说明：This package is superceded by @lottiefiles/dotlottie-react

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

- 包体积（解压后）：136 kB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react ^16\.8\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0
- 首次发布：2023-06-21T09:48:29.201Z
- 最新版本发布：2024-03-21T09:07:12.135Z
- 近 30 天下载量：171636（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：45（近 12 个月 0 个）

## 中文简介

dotlottie 动画播放器反应组件.

## 安装

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

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

## README

# Dot LottiePlayer 反应组件

![](https://user-images.githubusercontent.com/23125742/201124166-c2a0bc2a-018b-463b-b291-944fb767b5c2.png)

这是一个反应组件,用于在您的反应项目中轻而易举地嵌入和播放点Lottie动画.

## 什么是多特罗蒂?

dot Lottie是一种开源文件格式,将一个或多个 Lottie 文件及其相关资源合并为一个文件. 这些文件是使用Deflate压缩方法压缩的ZIP档案并有文件扩展".lottie".

[更多关于洛蒂点的信息!](https://dotlottie.io/)

## 文档

[查看全部文档](https://docs.lottiefiles.com/dotlottie-players/)

## 安装

您可以安装 `@dotlottie/react-player` 使用 npm :

```shell
npm install @dotlottie/react-player
```

线条 :

```shell
yarn add @dotlottie/react-player
```

## 使用量

用于 `@dotlottie/react-player` 在反应工程中,导入组件如下:

```jsx
import React from 'react';
import { DotLottiePlayer, Controls } from '@dotlottie/react-player';
import '@dotlottie/react-player/dist/index.css';

const App = () => {
  return (
    <div>
      <DotLottiePlayer
        src="/path-to-lottie.lottie"
        autoplay
        loop
      >
        <Controls />
      </DotLottiePlayer>
    </div>
  );
};

export default App;
```

## 道具

这个 `DotLottiePlayer` 组件接受下列道具:

| Prop | 说明 | 类型 | 默认 |
| --- | --- | --- | --- |
| `src` _(必须)_ | 动画数据或 URL | `Record<string, unknown> | string` | `undefined` |
| `lottieRef` | 获取玩家对象 | `MutableRefObject` | `undefined` |
| `autoplay` | 装入时自动播放动画 | `boolean` | `false` |
| `background` | 背景颜色 | `string` | `transparent` |
| `direction` | 播放方向 | `1 | -1` | `1` |
| `hover` | 是否在鼠标徘徊时播放 | `boolean` | `false` |
| `intermission` | 循环间暂停 | `number` | `0` |
| `loop` | 是否循环动画 | `boolean` | `false` |
| `playMode` | 播放模式 | `'normal' | 'bounce'` | `normal` |
| `renderer` | 如何实现 | `'svg' | 'html' | 'canvas'` | `svg` |
| `speed` | 播放速度 | `number` | `1` |
| `onEvent` | 听玩家的事件 | `function` | `undefined` |
| `defaultTheme` | 要使用的默认.lottie主题 | `string` | `undefined` |

## 活动

以下事件通过互联网曝光: `onEvent` 函数 :

| 名称 | 说明 |
| --- | --- |
| `complete` | 动画播放完成 |
| `error` | 动画源无法解析、无法装入或格式出错 |
| `frame` | 输入新框架 |
| `freeze` | 动画被冻结了 |
| `loopComplete` | 循环动画完成 |
| `pause` | 动画暂停 |
| `ready` | 动画数据已装入, 玩家已准备好 |
| `stop` | 动画停止了 |

## 实例

倾听事件:

```jsx
import React, { useState } from 'react';
import { DotLottiePlayer, Controls, PlayerEvents } from '@dotlottie/react-player';
import '@dotlottie/react-player/dist/index.css';

const App = () => {
  const [loading, setLoading] = useState(true);

  return (
    <div>
      {loading ? (
        <div>loading....</div>
      ) : (
        <DotLottiePlayer
          src="/path-to-lottie.lottie"
          onEvent={(event: PlayerEvents) => {
            if (event === PlayerEvents.Ready) {
              setLoading(false);
            }
          }}
          autoplay
          loop
        >
          <Controls />
        </DotLottiePlayer>
      )}
    </div>
  );
};

export default App;
```

获取玩家实例和调用方法 :

```jsx
import React, { useRef } from 'react';
import { DotLottiePlayer, Controls, PlayerEvents } from '@dotlottie/react-player';
import '@dotlottie/react-player/dist/index.css';

const App = () => {
  const lottieRef = useRef<DotLottieRefProps>();

  return (
    <div>
      <DotLottiePlayer
        lottieRef={lottieRef}
        src="/path-to-lottie.lottie"
        onEvent={(event: PlayerEvents) => {
          if (event === PlayerEvents.Ready) {
            // Play next animation.
            lottieRef.current?.next();
          }
        }}
        autoplay
        loop
      >
        <Controls />
      </DotLottiePlayer>
    </div>
  );
};

export default App;
```

## 方法

您可以使用玩家实例访问这些方法 :

-   `getLottie(): AnimationItem | undefined` 返回 [乐天网](https://www.npmjs.com/package/lottie-web) 举个例子.
    
-   `getManifest(): Manifest | undefined` 返回 `.lottie` 现相.
    
-   `next(getOptions?: (currPlaybackOptions?: PlaybackOptions, manifestPlaybackOptions?: PlaybackOptions) => PlaybackOptions): void` 播放列表中的下个动画.
    
-   `play(indexOrId?: string | number, getOptions?: (currPlaybackOptions?: PlaybackOptions, manifestPlaybackOptions?: PlaybackOptions) => PlaybackOptions): void` 播放当前动画或带有经过的回放选项的指定动画.
    
-   `previous(getOptions?: (currPlaybackOptions?: PlaybackOptions, manifestPlaybackOptions?: PlaybackOptions) => PlaybackOptions): void` 在列表中播放上一个动画.
    
-   `reset(): void` 重新设置或返回默认/初始动画 .
    
-   `resize(): void` 如果画布渲染器调整画布大小 .
    
-   `seek(frame: number): void` 寻找特定框架.
    
-   `setBackground(background: string): void` 设置容器背景 .
    
-   `setDefaultTheme(defaultTheme: string): void` 设置默认主题( 应用所有动画) .
    
-   `setDirection(direction: AnimationDirection): void` 设置玩家方向。 (应用所有动画)
    
-   `setHover(hover: boolean): void` 设定是否在悬浮上玩( 适用于所有动画) .
    
-   `setIntermission(intermission: number): void` 设置循环之间的暂停( 适用于所有动画) .
    
-   `setLoop(loop: number | boolean): void` 设置循环行为(适用于所有动画).
    
-   `setPlayMode(mode: PlayMode): void` 设定玩家对所有动画的玩法模式(如弹出或正常).
    
-   `setSpeed(speed: number): void` 设置播放速度( 应用所有动画) .
    
-   `togglePlay(): void` 切换游戏状态 .
    
-   `pause(): void` 暂停动画.
    
-   `stop(): void` 停止动画.
    
-   `getContainer(): HTMLDivElement | undefined` 得到动画容器.
    

## 捐款

我们使用更改器来维护此寄存器的更改日志 。 在对代码库做任何会影响功能或性能的修改时,我们要求显示一个更改器.

要添加更改列表, 运行 :

```
pnpm changeset add
```

选择您想要的版本缓冲类型(主要,次要,补丁).

您可以通过打开“. changerset”文件夹中创建的“. mdm”命令所创建的“. md”文件来记录细节变化,并正确使用Markdown格式。 打开文件,它应该看起来像这样:

```
---
"@dotlottie/common": minor
"@dotlottie/react-player": major
---

This is where you document your **changes** using Markdown.

- You can write
- However you'd like
- In as much detail as you'd like

Aim to provide enough details so that teammates and future you can understand the changes and the context of

 the change.
```

将您的更改和更改列表提交您的分支, 然后在开发分支上创建拉动请求 .

## 我们其他乐天图书馆

以下是我们其他与洛蒂有关的图书馆:

-   [lottie 反应](https://github.com/LottieFiles/lottie-react): Lottie Web 播放器的回放组件.
-   [洛特维](https://github.com/LottieFiles/lottie-vue):洛蒂玩家的Vue组件.
-   [斯维特-洛特-玩家](https://github.com/LottieFiles/svelte-lottie-player): Lottie 玩家组件用于斯维尔特.
-   [j 罗蒂](https://github.com/LottieFiles/jlottie): j Lottie作为通用乐天玩家是合适的,尽管它执行核心玩家中的一个子集特征. 这种做法导致一个很小的足迹和出色的业绩.
-   [乐蒂互动](https://github.com/LottieFiles/lottie-interactivity): 这是一个小库,用于在您 Lottie 动画中添加滚动,光标交互和交互链.
-   [劳蒂 -js](https://github.com/LottieFiles/lottie-js):库由将Lottie JSON映射到对象模型并和属性相互作用的方法组成,以及操纵它们的方法.

## 许可证

麻省理工学院许可证 ^ LottieFiles.com

## 常见问题

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

dotlottie 动画播放器反应组件\.注意：该包已被作者标记为弃用——This package is superceded by @lottiefiles/dotlottie-react

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

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

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

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

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

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

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

@dotlottie/react-player 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

最新版本 1\.6\.19 发布于 2024/03/21（2 年前）；至今共发布 45 个版本，其中过去 12 个月发布了 0 个；首次发布于 2023/06/21。作者已将其标记为弃用，新项目建议寻找替代方案。