APlayer 中文文档 下载 App

APlayer 通过 localStorage 记忆音量和循环设置

存储什么

APlayer 会自动把以下用户设置存到 localStorage：

初始化时 APlayer 会读取这些值，覆盖代码里传入的默认值。

默认存储位置

存储键名默认是 'aplayer-setting'：

localStorage.getItem('aplayer-setting');
// 可能的值: '{"volume":0.7,"loop":"all","order":"list","lrcShow":true,"listShow":true}'

自定义存储键名

storageName 参数可以改存储键名：

const ap = new APlayer({
    container: document.getElementById('aplayer'),
    storageName: 'my-site-music-setting',  // 自定义键名
    audio: [...]
});

什么时候需要自定义

场景为什么要改
一个域名下有多个独立的播放器避免它们互相覆盖
你想和自己的其他 localStorage 区分统一管理
你有"强制使用代码默认值"的场景每次用不同的 storageName 或提前清除

阻止存储

有两种方式阻止 localStorage 存储：

方式一：volume API 的 nostorage 参数

ap.volume(0.5, true);  // 第二个参数 true = 不写入 localStorage

但这只影响音量，不影响循环模式等其他设置。

方式二：提前清除

在初始化前手动清除 APlayer 的存储：

localStorage.removeItem('aplayer-setting');  // 或你的自定义 storageName
const ap = new APlayer({ ... });

方式三：使用不存在的 storageName

// 用一个每次都不同的名字（比如加时间戳或随机后缀）
const ap = new APlayer({
    storageName: 'aplayer-setting-' + Date.now(),
    // ...
});

这实际上就是禁用了持久化——因为每次的键名都不一样，上次的值读不到。

典型场景：强制默认值 vs 尊重用户

全站统一播放器

大多数场景下应该尊重用户选择：

// 推荐：让 localStorage 记忆用户偏好
const ap = new APlayer({
    theme: '#b7daff',  // 默认主题色
    volume: 0.7,       // 默认音量
    loop: 'all',       // 默认循环
    // 用户可以在界面上改，下次打开自动恢复
});

演示页 / 测评页

演示场景可能需要每次都是干净的初始状态：

// 初始化前清除
localStorage.removeItem('demo-aplayer-setting');

const ap = new APlayer({
    storageName: 'demo-aplayer-setting',
    // ...
});

多播放器各自独立

const ap1 = new APlayer({ storageName: 'player-main', ... });
const ap2 = new APlayer({ storageName: 'player-sidebar', ... });
const ap3 = new APlayer({ storageName: 'player-inline-article', ... });

// 每个播放器各自记忆自己的用户设置

注意事项