APlayer 播放列表管理 API

ap.list 是什么

ap.list 是 APlayer 实例上的一个命名空间对象，专门管理播放列表相关操作。它内部维护着当前的歌曲数组、当前索引等状态。

查看当前状态

console.log(ap.list.audios);    // 所有音频对象数组
console.log(ap.list.index);     // 当前播放歌曲的下标（从 0 开始）
console.log(ap.list);           // 整个 list 对象

添加音频

list.add(audios)

往播放列表尾部添加一个或多个音频。

// 添加单个音频
ap.list.add({
    name: '新歌曲名称',
    artist: '新艺术家',
    url: 'new-audio.mp3',
    cover: 'new-cover.jpg',
    lrc: 'new-lyrics.lrc',  // 可选
    theme: '#333'            // 可选，这首歌的主题色
});

// 批量添加
ap.list.add([
    { name: 'A', artist: '艺术家', url: 'a.mp3', cover: 'a.jpg' },
    { name: 'B', artist: '艺术家', url: 'b.mp3', cover: 'b.jpg' }
]);

添加成功后会触发 listadd 事件。

移除音频

list.remove(index)

按下标移除列表中的一首歌曲。

ap.list.remove(1);   // 移除第 2 首（下标从 0 开始）

如果移除的是当前正在播放的歌曲：

• 播放器会自动切到下一首
• 或者如果是最后一首，切到上一首

移除成功后会触发 listremove 事件。

切换当前播放

list.switch(index)

直接跳到指定下标的歌曲播放。

ap.list.switch(2);   // 切到第 3 首

这和 ap.skipForward() / ap.skipBack() 不同：

• skipForward() 按播放顺序逻辑（可能随机）选择下一首
• list.switch() 直接跳到指定下标

切换成功后会触发 listswitch 事件。

清空列表

list.clear()

清空整个播放列表。

ap.list.clear();

清空后：

• 播放器停止播放
• ap.list.audios 变成空数组 []
• ap.list.index 变成 0
• 触发 listclear 事件

列表显示 / 隐藏

list.show()

强制展开列表（覆盖 listFolded 设置）。

ap.list.show();

list.hide()

强制折叠列表。

ap.list.hide();

list.toggle()

切换展开 / 折叠状态。

ap.list.toggle();

完整示例：动态歌单管理

const ap = new APlayer({
    container: document.getElementById('aplayer'),
    audio: [
        { name: '初始歌曲', artist: '默认', url: 'default.mp3', cover: 'default.jpg' }
    ]
});

// 添加几首新歌
ap.list.add([
    { name: '新歌一', artist: 'A', url: '1.mp3', cover: '1.jpg' },
    { name: '新歌二', artist: 'B', url: '2.mp3', cover: '2.jpg' }
]);

// 切到新歌一
ap.list.switch(1);

// 监听事件
ap.on('listadd', function(audio) {
    console.log('添加了:', audio.name);
});

ap.on('listremove', function(audio) {
    console.log('移除了:', audio.name);
});

ap.on('listswitch', function(index) {
    console.log('切到第', index + 1, '首');
});