# @gumlet/player\.js 中文文档

规范地址：https://npmcn.com/package/%40gumlet/player.js/

版本：3\.0\.11
npm 元数据更新时间：2026-09-29T09:52:03.515Z
中文译文更新时间：2026-11-17T03:33:55.178Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gumlet/player.js
原文对照：https://npmcn.com/package/%40gumlet/player.js/?lang=original
项目主页：http://github.com/gumlet/player.js
源码仓库：https://github.com/gumlet/player.js

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

- 包体积（解压后）：202 kB，11 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2023-05-24T21:29:49.745Z
- 最新版本发布：2026-09-29T09:52:03.146Z
- 近 30 天下载量：13610（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：33（近 12 个月 9 个）

## 中文简介

玩家.js =========

## 安装

```sh
npm install @gumlet/player.js
```

也可以使用：`pnpm add @gumlet/player.js`、`yarn add @gumlet/player.js`、`bun add @gumlet/player.js`

## README

# 玩家.js (英语)

[![](https://data.jsdelivr.com/v1/package/npm/@gumlet/player.js/badge)](https://www.jsdelivr.com/package/npm/@gumlet/player.js) [![](https://img.shields.io/npm/v/@gumlet/player.js.svg)](https://www.npmjs.com/package/@gumlet/player.js)

用于与支持 Player.js spec 的 Iframes 交互的 JavaScript 库.

```js
const player = new playerjs.Player('iframe');

player.on('ready', async () => {
  player.on('play', () => {
    console.log('play');
  });

  const duration = await player.getDuration();
  console.log(duration);

  if (player.supports('method', 'mute')) {
    await player.mute();
  }

  await player.play();
});
```

## 安装

Player.js在JSDelivr的CDN上主播:

```html
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@gumlet/player.js@3.0/dist/main.global.js"></script>
```

通过 npm 安装 :

```sh
npm install @gumlet/player.js
```

## 类型脚本支持

Player.js v3.0.0+包括包含类型定义的完整类型脚本支持. 库以 TypeScript 书写,并提供全面类型安全:

```typescript
import playerjs from '@gumlet/player.js';

const player = new playerjs.Player('iframe');

player.on('ready', async () => {
  try {
    const duration = await player.getDuration();
    console.log(`Duration: ${duration} seconds`);
    
    if (player.supports('method', 'mute')) {
      await player.mute();
    }
    
    await player.play();
  } catch (error) {
    console.error('Player error:', error);
  }
});
```

### 基于承诺的API

所有玩家方法都返回承诺,使使用Aync/await模式的工作更容易:

```typescript
// Get multiple values concurrently
const [duration, currentTime, volume] = await Promise.all([
  player.getDuration(),
  player.getCurrentTime(),
  player.getVolume()
]);

// Chain operations
await player.setCurrentTime(10);
await player.setVolume(75);
await player.play();
```

## 准备

由于我们需要在两个Iframe之间跳起舞,你应该一直等到 `ready` 事件在与玩家对象互动前起火。 然而,玩家会在内部排队消息,直到准备完毕:

```js
const player = new playerjs.Player('iframe');

player.on('ready', async () => {
  await player.setCurrentTime(20);
});
```

## 时间安排

Iframe 添加时和 发射时之间的时间很重要。 可悲的是,我们不能在iframe装上之前就发射已准备好的事件,但是没有具体的方法来说明我们何时可以得到邮戳.

最好的办法是做以下工作:

### 通过 JavaScript 创建 Iframe

```js
const iframe = document.createElement('iframe');
iframe.src = 'https://example.com/iframe';
document.body.appendChild(iframe);

const player = new playerjs.Player(iframe);
```

在这种情况下,Player.js会收听iframe的上载事件,只在准备就绪时尝试交流.

### 等着文件准备好

```html
<iframe src="//example.com/iframe"></iframe>

<script>
  $(document).on('ready', () => {
    $('iframes').each(async () => {
      const player = new playerjs.Player(this);
      player.on('ready', async () => {
        await player.play();
      });
    });
  });
</script>
```

此时此刻,我们可以合理地假设 iframe's 装载和准备。 player.js会关注在玩家被设置前被炒作的已准备好事件.

## 方法

所有方法都为现代合成/等待模式返回承诺:

### `play(): Promise<void>`

播放媒体:

```js
await player.play();
```

### `pause(): Promise<void>`

暂停媒体:

```js
await player.pause();
```

### `getPaused(): Promise<boolean>`

确定媒体是否被暂停 :

```js
const isPaused = await player.getPaused();
console.log('paused:', isPaused);
```

### `mute(): Promise<void>`

压制媒体:

```js
await player.mute();
```

### `unmute(): Promise<void>`

揭发媒体:

```js
await player.unmute();
```

### `getMuted(): Promise<boolean>`

确定媒体是否变音 :

```js
const isMuted = await player.getMuted();
console.log('muted:', isMuted);
```

### `setVolume(volume: number): Promise<void>`

设出出卷. 值必须在 0- 100 之间 :

```js
await player.setVolume(50);
```

### `getVolume(): Promise<number>`

取出音量来. 数值为 0- 100 :

```js
const volume = await player.getVolume();
console.log('volume:', volume);
```

### `getDuration(): Promise<number>`

以秒计媒体持续时间 :

```js
const duration = await player.getDuration();
console.log('duration:', duration);
```

### `setCurrentTime(time: number): Promise<void>`

以秒计执行特定时间的搜索 :

```js
await player.setCurrentTime(50);
```

### `getCurrentTime(): Promise<number>`

获取视频秒的当前时间 :

```js
const currentTime = await player.getCurrentTime();
console.log('currentTime:', currentTime);
```

### `setPlaybackRate(rate: number): Promise<void>`

设定播放器中可用的播放率 。 如果没有播放率, 不返回错误 :

```js
await player.setPlaybackRate(0.5);
```

### `getPlaybackRate(): Promise<number>`

获取玩家当前播放率 :

```js
const rate = await player.getPlaybackRate();
console.log('playbackRate:', rate);
```

### `setLoop(loop: boolean): Promise<void>`

设定媒体是否循环 :

```js
await player.setLoop(true);
```

### `getLoop(): Promise<boolean>`

获取媒体是否设定循环 :

```js
const isLooping = await player.getLoop();
console.log('looping:', isLooping);
```

### `off(event: string, callback?: Function): void`

删除事件听众 。 如果指定了听众,只应删除该听众,否则就删除所有听众:

```js
player.off('play');
player.off('play', playCallback);
```

### `destroy(): void`

删除玩家的 `window` `message` 收听器和排入队列的清晰调用符, 这样实例可以被垃圾收集 。 在一页的应用程序中拆掉玩家( 或任何不再需要实例时) 时使用此选项 :

```js
player.destroy();
```

之后 `destroy()`,该玩家不应被再次使用.

### `on(event: string, callback: Function): void`

添加事件倾听器 :

```js
player.on('play', () => console.log('play'));
```

### `supports(type: 'method' | 'event', name: string | string[]): boolean`

确定玩家是否支持某一事件或方法:

```js
player.supports('method', 'getDuration');
player.supports('event', 'ended');
player.supports('method', ['play', 'pause']);
```

## 活动

Player.js提供综合事件处理,以监控回放状态和用户互动. 所有事件都可以使用 `on()` 方法.

### 核心活动

#### `ready`

当媒体准备好接收命令时即被开除. 在调用玩家方法之前, 总是等待此事件 .

```js
player.on('ready', async () => {
  console.log('Player is ready!');
  // Safe to call player methods now
  await player.play();
});
```

**说明:** 如PlayerJs Spec中概述的,如果页面上有多个玩家有相同的玩家,则可能会遇到不一致的情况 `src`。为了避免出现这种情况,在 Iframe 的 src 上附加一个 UUID 或时间戳 .

#### `play`

回放开始时被解除.

```js
player.on('play', () => {
  console.log('Video started playing');
});
```

#### `pause`

回放暂停时被解除 .

```js
player.on('pause', () => {
  console.log('Video paused');
});
```

#### `ended`

回放到媒体末端后被解除.

```js
player.on('ended', async () => {
  console.log('Video finished');
  // Reset to beginning if needed
  await player.setCurrentTime(0);
});
```

### 进度事件

#### `timeupdate`

在播放时定期以当前时间信息放出 .

```js
player.on('timeupdate', (data) => {
  const { seconds, duration } = data;
  const progress = (seconds / duration) * 100;
  
  console.log(`Progress: ${progress.toFixed(1)}%`);
  console.log(`Current time: ${formatTime(seconds)} / ${formatTime(duration)}`);
});

function formatTime(seconds) {
  const mins = Math.floor(seconds / 60);
  const secs = Math.floor(seconds % 60);
  return `${mins}:${secs.toString().padStart(2, '0')}`;
}
```

#### `progress`

当媒体缓冲/加载额外内容时被解除.

```js
player.on('progress', (data) => {
  const { percent } = data;
  console.log(`Buffered: ${(percent * 100).toFixed(1)}%`);
});
```

#### `seeked`

当用户寻求不同的时间位置时即被解除.

```js
player.on('seeked', (data) => {
  const { seconds, duration } = data;
  console.log(`Seeked to ${seconds}s of ${duration}s`);
});
```

### 音频/视频控制事件

#### `volumeChange`

当音量关卡变化时起火,包括哑/哑动作.

```js
player.on('volumeChange', async () => {
  const volume = await player.getVolume();
  const isMuted = await player.getMuted();
  
  console.log(`Volume: ${volume}%, Muted: ${isMuted}`);
});
```

#### `playbackRateChange`

回放速度改变后被解除 .

```js
player.on('playbackRateChange', async () => {
  const rate = await player.getPlaybackRate();
  console.log(`Playback rate: ${rate}x`);
});
```

### 显示事件

#### `fullscreenChange`

全屏模式被切换后被解除 .

```js
player.on('fullscreenChange', (data) => {
  const { isFullScreen } = data;
  console.log(`Fullscreen: ${isFullScreen}`);
});
```

#### `pipChange`

Picture-in-Picture 模式被切换后被解除.

```js
player.on('pipChange', (data) => {
  const { isPIP } = data;
  console.log(`Picture-in-Picture: ${isPIP}`);
});
```

### 质量事件

#### `qualityChange`

当视频质量/分辨率被改变时被解除.

```js
player.on('qualityChange', (data) => {
  const { quality } = data;
  console.log(`Quality changed to: ${quality}`);
});
```

#### `audioChange`

音轨被更改后被放出.

```js
player.on('audioChange', (data) => {
  console.log('Audio track changed:', data);
});
```

### 字幕事件

#### `subtitleChange`

当字幕/字幕音轨被打开,关闭,或切换到另一种语言时被解除.

```js
player.on('subtitleChange', (data) => {
  const { showing, language } = data;
  console.log(showing ? `Subtitles on (${language})` : 'Subtitles off');
});
```

### 处理错误

#### `error`

回放时发生错误时被解除 .

```js
player.on('error', (error) => {
  console.error('Playback error:', error);
  // Handle error appropriately for your application
});
```

### 完整示例

以下是一个全面的例子,说明如何倾听多起事件:

```js
const player = new playerjs.Player('video-iframe');

player.on('ready', async () => {
  console.log('Player is ready!');
  
  // Get initial player state
  const duration = await player.getDuration();
  const volume = await player.getVolume();
  const isPaused = await player.getPaused();
  
  console.log(`Duration: ${duration}s, Volume: ${volume}%, Paused: ${isPaused}`);
});

// Listen to playback events
player.on('play', () => console.log('Started playing'));
player.on('pause', () => console.log('Paused'));
player.on('ended', () => console.log('Playback finished'));

// Listen to progress events
player.on('timeupdate', (data) => {
  const { seconds, duration } = data;
  console.log(`${seconds.toFixed(1)}s / ${duration.toFixed(1)}s`);
});

// Listen to user interaction events
player.on('volumeChange', async () => {
  const volume = await player.getVolume();
  const muted = await player.getMuted();
  console.log(`Volume: ${volume}%, Muted: ${muted}`);
});

player.on('seeked', (data) => {
  console.log(`Seeked to: ${data.seconds}s`);
});

// Listen to display events
player.on('fullscreenChange', (data) => {
  console.log(`Fullscreen: ${data.isFullScreen}`);
});

player.on('pipChange', (data) => {
  console.log(`Picture-in-Picture: ${data.isPIP}`);
});

// Handle errors
player.on('error', (error) => {
  console.error('Player error:', error);
});
```

## 相关文档

-   [接收方实施指南](https://npmcn.com/package/%40gumlet/player.js/RECEIVER.md) - 在您的视频播放器中执行 Player.js spec
-   [遗产调回 API](https://npmcn.com/package/%40gumlet/player.js/CALLBACK_API.md) - 基于后向兼容的回调方法的文档

## 常见问题

### @gumlet/player\.js 是什么？

玩家\.js =========

### 如何安装 @gumlet/player\.js？

在项目目录运行 npm install @gumlet/player\.js，或使用 pnpm add / yarn add / bun add。

### @gumlet/player\.js 支持 TypeScript 吗？

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

### @gumlet/player\.js 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @gumlet/player\.js 可以商用吗？

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

### @gumlet/player\.js 的下载量有多少？

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

### @gumlet/player\.js 还在维护吗？

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

