APlayer 播放控制 API 全集

实例化后的访问方式

通过 CDN 引入时，APlayer 是全局类；通过 npm + import 时，APlayer 是导入的类。两者用法一致：

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

所有 API 通过实例调用，比如 ap.play()。

播放与暂停

play()

开始播放当前歌曲。

ap.play();

注意：移动端浏览器几乎都会阻止自动播放。ap.play() 如果在页面加载完成时立即调用，很可能不会生效——浏览器需要用户交互（点击、触摸等）后才允许播放。详见自动播放策略。

pause()

暂停当前歌曲。

ap.pause();

toggle()

切换播放 / 暂停状态。如果正在播放则暂停，如果暂停则开始播放。

ap.toggle();

实际用途

这三个 API 常用来控制页面上的自定义播放按钮：

// 绑定自定义按钮
document.getElementById('my-play-btn').addEventListener('click', function() {
    ap.toggle();
});

// 响应播放状态变化更新按钮图标
ap.on('play', function() {
    document.getElementById('my-play-btn').textContent = '暂停';
});
ap.on('pause', function() {
    document.getElementById('my-play-btn').textContent = '播放';
});

跳转播放进度

seek(time)

跳转到指定时间点。单位是秒，支持小数。

ap.seek(30);          // 跳到第 30 秒
ap.seek(3.5);         // 跳到第 3.5 秒
ap.seek(ap.audio.duration / 2);  // 跳到一半位置

实际用途

"重新从开头播放"：ap.seek(0);
"跳过前奏"：ap.seek(10);
配合进度条的 click 事件：用户点击进度条时计算百分比，转成秒数传给 seek

切换歌曲

skipBack()

切换到上一首歌曲。行为取决于当前播放位置：

如果当前歌曲已播放超过 3 秒，跳到当前歌曲开头
如果当前歌曲已播放不足 3 秒，跳到上一首

ap.skipBack();

skipForward()

切换到下一首歌曲。

ap.skipForward();

与列表索引直接跳转的区别

skipBack() / skipForward() 是"上一首 / 下一首"的语义，受 order（顺序 / 随机）设置影响
ap.list.switch(index) 是直接跳到指定下标，不受 order 影响

音量控制

volume(percentage, nostorage)

设置音量。两个参数都可选。

ap.volume(0.5);             // 设为 50% 音量
ap.volume(0.5, true);       // 设为 50% 但不写入 localStorage
ap.volume(0);               // 静音
ap.volume(1);               // 最大音量

参数	类型	默认值	说明
percentage	number	必填	音量值，范围 0 ~ 1
nostorage	boolean	`false`	是否阻止写入 localStorage。默认会记忆用户设置

模式切换

setMode(mode)

切换播放器的显示模式。

ap.setMode('mini');     // 切到迷你模式
ap.setMode('normal');   // 切回正常模式

mode 参数只接受 'mini' 和 'normal' 两个值。吸底模式（fixed）不支持运行时切换——需要销毁后重新实例化。

mode 属性

console.log(ap.mode);   // 'mini' 或 'normal'

销毁播放器

destroy()

完全销毁 APlayer 实例，清理 DOM 和事件绑定。

ap.destroy();
ap = null;  // 建议手动设为 null 防止内存泄漏

销毁后容器元素恢复为空，可以重新实例化新的播放器。在 Vue / React 的组件生命周期钩子中尤其重要——详见销毁与重建。