@gumlet/player.js

中文文档
3.0.11发布于 2026/09/29MITTypeScriptESM + CJS零依赖构建来源已验证近 30 天下载 1.4万

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

中文使用文档
文档目录37 节
  1. 安装
  2. 类型脚本支持
  3. 基于承诺的API
  4. 准备
  5. 时间安排
  6. 通过 JavaScript 创建 Iframe
  7. 等着文件准备好
  8. 方法
  9. play(): Promise<void>
  10. pause(): Promise<void>
  11. getPaused(): Promise<boolean>
  12. mute(): Promise<void>
  13. unmute(): Promise<void>
  14. getMuted(): Promise<boolean>
  15. setVolume(volume: number): Promise<void>
  16. getVolume(): Promise<number>
  17. getDuration(): Promise<number>
  18. setCurrentTime(time: number): Promise<void>
  19. getCurrentTime(): Promise<number>
  20. setPlaybackRate(rate: number): Promise<void>
  21. getPlaybackRate(): Promise<number>
  22. setLoop(loop: boolean): Promise<void>
  23. getLoop(): Promise<boolean>
  24. off(event: string, callback?: Function): void
  25. destroy(): void
  26. on(event: string, callback: Function): void
  27. supports(type: 'method' | 'event', name: string | string[])…
  28. 活动
  29. 核心活动
  30. 进度事件
  31. 音频/视频控制事件
  32. 显示事件
  33. 质量事件
  34. 字幕事件
  35. 处理错误
  36. 完整示例
  37. 相关文档

玩家.js (英语)

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

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上主播:

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@gumlet/[email protected]/dist/main.global.js"></script>

通过 npm 安装 :

npm install @gumlet/player.js

类型脚本支持

Player.js v3.0.0+包括包含类型定义的完整类型脚本支持. 库以 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模式的工作更容易:

// 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 事件在与玩家对象互动前起火。 然而,玩家会在内部排队消息,直到准备完毕:

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

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

时间安排

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

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

通过 JavaScript 创建 Iframe

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

const player = new playerjs.Player(iframe);

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

等着文件准备好

<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>

播放媒体:

await player.play();

pause(): Promise<void>

暂停媒体:

await player.pause();

getPaused(): Promise<boolean>

确定媒体是否被暂停 :

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

mute(): Promise<void>

压制媒体:

await player.mute();

unmute(): Promise<void>

揭发媒体:

await player.unmute();

getMuted(): Promise<boolean>

确定媒体是否变音 :

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

setVolume(volume: number): Promise<void>

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

await player.setVolume(50);

getVolume(): Promise<number>

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

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

getDuration(): Promise<number>

以秒计媒体持续时间 :

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

setCurrentTime(time: number): Promise<void>

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

await player.setCurrentTime(50);

getCurrentTime(): Promise<number>

获取视频秒的当前时间 :

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

setPlaybackRate(rate: number): Promise<void>

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

await player.setPlaybackRate(0.5);

getPlaybackRate(): Promise<number>

获取玩家当前播放率 :

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

setLoop(loop: boolean): Promise<void>

设定媒体是否循环 :

await player.setLoop(true);

getLoop(): Promise<boolean>

获取媒体是否设定循环 :

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

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

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

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

destroy(): void

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

player.destroy();

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

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

添加事件倾听器 :

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

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

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

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

活动

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

核心活动

ready

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

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

回放开始时被解除.

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

pause

回放暂停时被解除 .

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

ended

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

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

进度事件

timeupdate

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

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

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

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

seeked

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

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

音频/视频控制事件

volumeChange

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

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

playbackRateChange

回放速度改变后被解除 .

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

显示事件

fullscreenChange

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

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

pipChange

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

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

质量事件

qualityChange

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

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

audioChange

音轨被更改后被放出.

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

字幕事件

subtitleChange

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

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

处理错误

error

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

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

完整示例

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

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);
});

版本与发布记录

@gumlet/player.js 共发布 33 个版本,首次发布于 2023/05/25;过去 12 个月发布了 9 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
3.0.11latest2026/09/291 个月前
3.0.102026/09/291 个月前
3.0.92026/07/283 个月前
3.0.82026/03/148 个月前
3.0.72026/03/148 个月前
3.0.62026/03/148 个月前

关于 @gumlet/player.js 的常见问题

@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 和提交记录判断。