五、事件系统
Clappr 拥有完善的事件系统，允许你监听播放器的各种状态变化，并执行相应的业务逻辑。
5.1 主要事件
5.2 基本用法
const player = new Clappr.Player({
source: 'your-video.mp4',
parentId: '#player',
events: {
onReady: () => console.log('播放器准备就绪'),
onPlay: () => console.log('开始播放'),
onPause: () => console.log('已暂停'),
onEnded: () => console.log('播放结束'),
onError: (err) => console.error('播放出错', err),
onTimeUpdate: ({ current, total }) => {
console.log(`播放进度：${current}/${total}秒`);
},
},
});
5.3 进阶使用
除了直接在初始化时通过 events 属性绑定，你还可以在获得播放器实例后动态地监听或解绑事件：
player.on(Clappr.Events.PLAYER_PLAY, () => { console.log('动态监听：播放'); });
player.once(Clappr.Events.PLAYER_ENDED, () => { console.log('动态监听（执行一次）：播放结束'); });
player.off(Clappr.Events.PLAYER_PAUSE);
对于 @clappr/core 用户，一些更底层的事件需要通过 player.core 或 player.core.activeContainer 来访问：
player.core.activeContainer.on(Clappr.Events.CONTAINER_STATE_BUFFERING, () => {
console.log('视频正在缓冲...');
});
六、插件的使用与扩展
插件是 Clappr 生态的灵魂。你可以通过插件为播放器添加新功能，也可以开发自定义插件来满足特定需求。
6.1 使用官方插件
步骤1：安装插件
npm install @clappr/hlsjs-playback
步骤2：引入并注册
<script src="https://cdn.jsdelivr.net/npm/@clappr/hlsjs-playback@latest/dist/hlsjs-playback.min.js"></script>
import HlsjsPlayback from '@clappr/hlsjs-playback';
const player = new Clappr.Player({
source: 'https://your-hls-stream.m3u8',
parentId: '#player',
plugins: {
playback: [HlsjsPlayback],
},
});
6.2 使用内置插件
在 v-clappr 组件中，许多功能（如 MediaControl、Poster、WaterMark 等）都是以插件形式提供的，并自动集成。使用 @clappr/player 时，基础功能已集成；使用 @clappr/core 时需手动引入：
import { Player } from '@clappr/core';
import { MediaControl, Poster, SpinnerThreeBounce } from '@clappr/plugins';
import HlsjsPlayback from '@clappr/hlsjs-playback';
const player = new Player({
source: 'https://your-hls-stream.m3u8',
parentId: '#player',
plugins: {
playback: [HlsjsPlayback],
container: [MediaControl, Poster, SpinnerThreeBounce],
},
});
6.3 第三方插件生态
Clappr 拥有活跃的社区，你可以从中找到许多优秀的第三方插件来扩展播放器功能：
6.4 禁用/覆盖默认插件
禁用插件：获取插件实例后调用 disable 方法：
player.getPlugin('spinner').disable();
覆盖插件：创建同名的自定义插件进行替换：
class NoSpinner extends Clappr.UIContainerPlugin {
get name() { return 'spinner'; } // 使用相同的插件名
}
const player = new Clappr.Player({ plugins: [NoSpinner] });
七、高级功能与定制
7.1 媒体控件（Media Control）
MediaControl 是 Clappr 默认提供的用户界面组件，开发者可以对其进行样式和行为的定制。
const player = new Clappr.Player({
mediacontrol: {
seekbar: '#ff0000', // 进度条颜色（红色）
buttons: '#ffffff', // 按钮图标颜色（白色）
},
hideMediaControl: false, // 是否一直显示控制栏（false 表示不自动隐藏）
hideMediaControlDelay: 3000, // 控制栏自动隐藏的延迟（毫秒）
hideVolumeBar: false, // 是否隐藏音量控制条
});
7.2 禁用下载与右键菜单
可以通过多种方式实现禁用下载和右键菜单的效果：
方法一：监听 'ready' 事件操作 DOM（推荐）：
player.on('ready', () => {
const videoElement = document.querySelector('[data-html5-video]');
if (videoElement) {
videoElement.setAttribute('controlslist', 'nodownload');
videoElement.addEventListener('contextmenu', (e) => e.preventDefault());
}
});
方法二：创建自定义插件（更稳健，适合企业级应用）：
const CustomControlsPlugin = Clappr.CorePlugin.extend({
bindEvents() {
this.listenTo(this.core.mediaControl, 'mediacontrol:containerchanged', this.onContainerChanged);
},
onContainerChanged() {
const videoElement = this.core.getCurrentContainer().$el.find('video')[0];
if (videoElement) {
videoElement.setAttribute('controlslist', 'nodownload');
videoElement.addEventListener('contextmenu', (e) => e.preventDefault());
}
},
});
const player = new Clappr.Player({
plugins: [CustomControlsPlugin],
});
7.3 自动播放策略与处理
随着浏览器安全策略的收紧，自动播放已成为 Web 开发中的一个挑战。Clappr 本身无法绕开浏览器的限制，但你可以通过为播放器设置静音（mute: true）来绕过这项限制。
来源：
const player = new Clappr.Player({
autoPlay: true,
mute: true, // 关键点：静音播放
});
