APlayer 中文文档 下载 App

APlayer 音频事件完整列表

绑定方式

APlayer 的事件绑定统一用 ap.on(event, handler)：

ap.on('play', function() {
    console.log('音频开始播放了');
});

ap.on('error', function() {
    console.log('音频加载或播放出错');
});

所有原生 HTML5 Audio 事件都会被 APlayer 透传。此外 APlayer 还有自己特有的播放器事件（见下一页 播放器事件）。

音频事件完整列表

以下事件全部来自 HTML5 Audio / Video 标准，在恰当的时机自动触发。

事件触发时机
abort音频被中止加载（不是由于错误）
canplay音频已经可以开始播放（浏览器有足够缓冲）
canplaythrough浏览器可以流畅播放到结尾（整个音频缓冲完成）
durationchange音频总时长发生变化
emptied播放列表被清空或音频源重置
ended当前歌曲播放完毕
error音频加载或播放出错
loadeddata音频当前帧加载完成
loadedmetadata音频元数据（时长、大小等）加载完成
loadstart开始加载音频
mozaudioavailable（APlayer 特有）音频数据可用
pause音频暂停
play音频开始播放（首次）
playing音频正在播放（从暂停或缓冲中恢复也算）
progress音频正在下载（周期性触发）
ratechange播放速率发生变化
seeked跳转完成（seek 操作结束）
seeking正在跳转（seek 操作进行中）
stalled浏览器尝试加载但没有数据返回
suspend加载被暂停（可能是网络原因）
timeupdate当前播放位置更新（约每秒 4 次）
volumechange音量发生变化
waiting播放被暂停以等待更多缓冲数据

最常用的几个事件

play / pause

最常用的一对事件，用来同步 UI 状态：

let isPlaying = false;

ap.on('play', () => isPlaying = true);
ap.on('pause', () => isPlaying = false);
ap.on('ended', () => isPlaying = false);

timeupdate

约每秒触发 4 次，用来更新自定义进度显示：

ap.on('timeupdate', function() {
    const current = ap.audio.currentTime;  // 当前时间（秒）
    const duration = ap.audio.duration;   // 总时长（秒）
    const percent = (current / duration) * 100;
    console.log(`进度：${percent.toFixed(1)}%`);
});

ended

当前歌曲播完时触发，用来做后续处理：

ap.on('ended', function() {
    console.log('这首歌播完了');
    // 比如：自动切到下一首（APlayer 默认就会做）
    // 或者：跳转到某个页面
    // 或者：显示"谢谢收听"
});

error

出错时触发，通常需要特殊处理：

ap.on('error', function() {
    console.log('音频错误，可能原因：');
    console.log('- URL 404 或过期');
    console.log('- CORS 跨域问题');
    console.log('- 浏览器不支持的格式');
    console.log('- 网络中断');
});

区分 play 和 playing

在大多数场景下这两个事件的效果类似，选一个用就好。

与原生 audio 的关系

ap.audio 就是底层的原生 <audio> 元素，你可以直接访问它的所有属性：

console.log(ap.audio.currentTime);   // 当前播放时间
console.log(ap.audio.duration);      // 总时长
console.log(ap.audio.paused);        // 是否暂停
console.log(ap.audio.buffered);      // 已缓冲范围
console.log(ap.audio.src);           // 当前音频地址

ap.on() 内部就是在 ap.audio 上绑定了事件监听，所以你也可以直接写 ap.audio.addEventListener(...)——效果一样，但推荐用 ap.on() 保持代码风格统一。