玩家.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);
});