APlayer 特有播放器事件列表

与音频事件的区别

上一页音频事件是底层 HTML5 Audio 原生事件，由浏览器触发。本页的事件是 APlayer 自己实现的、在播放器层面触发的事件，与具体音频无关。

对比项	音频事件	播放器事件
触发者	浏览器（HTML5 Audio API）	APlayer 自身逻辑
含义	具体音频的加载、播放、出错等	播放器 UI 和结构的变化
数量	20+ 个（标准事件）	13 个
典型事件	play、pause、ended、error	listshow、listswitch、lrcshow、destroy

播放器事件完整列表

列表相关（6 个）

事件	触发时机
`listshow`	播放列表展开
`listhide`	播放列表折叠
`listadd`	添加一个或多个音频到列表
`listremove`	从列表移除一个音频
`listswitch`	切换到列表中另一首音频
`listclear`	清空整个播放列表

歌词相关（2 个）

事件	触发时机
`lrcshow`	歌词区域显示
`lrchide`	歌词区域隐藏

通知相关（2 个）

事件	触发时机
`noticeshow`	通知消息弹出
`noticehide`	通知消息消失

其他（3 个）

事件	触发时机
`destroy`	播放器被销毁
`volumechange`	音量变化（此事件同时属于音频事件和播放器事件）
`themechange`	主题色变化（部分版本支持）

示例代码

监听全部列表事件

const ap = new APlayer({ ... });

ap.on('listshow', () => console.log('列表展开'));
ap.on('listhide', () => console.log('列表折叠'));
ap.on('listadd', (audio) => console.log('添加:', audio.name));
ap.on('listremove', (audio) => console.log('移除:', audio.name));
ap.on('listswitch', (index) => console.log('切到第', index + 1, '首'));
ap.on('listclear', () => console.log('列表清空'));

监听歌词显隐

ap.on('lrcshow', () => {
    document.getElementById('lrc-btn').textContent = '隐藏歌词';
});

ap.on('lrchide', () => {
    document.getElementById('lrc-btn').textContent = '显示歌词';
});

监听销毁

ap.on('destroy', () => {
    console.log('播放器已销毁');
    // 在这里清理自定义引用
    ap = null;
});

listswitch 的 index 参数

listswitch 事件的回调函数会接收一个 index 参数，这是新歌曲在数组中的下标（从 0 开始）。

ap.on('listswitch', function(index) {
    const audio = ap.list.audios[index];
    console.log(`切到: ${audio.name} - ${audio.artist}（第 ${index + 1} 首）`);
});

事件的触发顺序

以一次正常的歌曲切换为例，事件触发顺序是：

pause（旧歌曲暂停）
listswitch（列表切换到新歌曲）
play / playing（新歌曲开始播放）
listswitch 之后如果新歌曲有自己的 theme，主题色会跟着变

以一次 list.add() 为例：

listadd（触发一次，即使添加了多个音频）

以一次 ap.destroy() 为例：

暂停当前播放
清理 DOM 元素
destroy（触发）

事件解绑

APlayer 不提供单独的 off() 方法。如果需要解绑事件：

// 方式一：销毁整个播放器（所有事件自动清除）
ap.destroy();

// 方式二：自行维护回调函数的引用（推荐做法）
function myPlayHandler() { ... }
ap.on('play', myPlayHandler);

// 如果需要解绑，可以改写 APlayer 的事件系统或直接 ap.destroy()
// 实际上大多数场景不需要解绑——destroy 会自动处理

简单说：不需要纠结解绑。ap.destroy() 会一次性清理所有事件绑定和 DOM 操作。