DavidZhang73.github.io/aplayer/docs/zh-Hans/README.html

<hr>
<h2 id="nav-zh-Hanssearch-zh-Hans"><a class="header-anchor" href="#nav-zh-Hanssearch-zh-Hans">¶</a>nav: zh-Hans<br>
search: zh-Hans</h2>
<h1>APlayer</h1>
<p>🍭 Wow, such a beautiful HTML5 music player</p>
<h2 id="特别赞助商"><a class="header-anchor" href="#特别赞助商">¶</a>特别赞助商</h2>
<a href="https://www.dogecloud.com/?ref=dplayer" target="_blank">
    <img width="222px" src="https://i.imgur.com/BBKXPAp.png">
</a>
<a href="https://console.upyun.com/register/?invite=BkLZ2Xqob" target="_blank">
    <img width="222px" src="https://imgur.com/apG1uKf.png">
</a>
<h2 id="安装"><a class="header-anchor" href="#安装">¶</a>安装</h2>
<p>使用 npm:</p>
<pre><code>npm install aplayer --save
</code></pre>
<p>使用 Yarn:</p>
<pre><code>yarn add aplayer
</code></pre>
<h2 id="入门"><a class="header-anchor" href="#入门">¶</a>入门</h2>
<div class="aplayer-wrap">
    <div id="aplayer2"><button class="docute-button load">点击加载播放器</div>
</div>
<pre><code class="language-html">&lt;link rel=&quot;stylesheet&quot; href=&quot;APlayer.min.css&quot;&gt;
&lt;div id=&quot;aplayer&quot;&gt;&lt;/div&gt;
&lt;script src=&quot;APlayer.min.js&quot;&gt;&lt;/script&gt;
</code></pre>
<pre><code class="language-js">const ap = new APlayer({
    container: document.getElementById('aplayer'),
    audio: [{
        name: 'name',
        artist: 'artist',
        url: 'url.mp3',
        cover: 'cover.jpg'
    }]
});
</code></pre>
<p>使用模块管理器:</p>
<pre><code class="language-js">import 'APlayer/dist/APlayer.min.css';
import APlayer from 'APlayer';

const ap = new APlayer(options);
</code></pre>
<h2 id="参数"><a class="header-anchor" href="#参数">¶</a>参数</h2>
<table>
<thead>
<tr>
<th>名称</th>
<th>默认值</th>
<th>描述</th>
</tr>
</thead>
<tbody>
<tr>
<td>container</td>
<td>document.querySelector(’.aplayer’)</td>
<td>播放器容器元素</td>
</tr>
<tr>
<td>fixed</td>
<td>false</td>
<td>开启吸底模式, <a href="https://aplayer.js.org/#/home?id=fixed-mode">详情</a></td>
</tr>
<tr>
<td>mini</td>
<td>false</td>
<td>开启迷你模式, <a href="https://aplayer.js.org/#/home?id=mini-mode">详情</a></td>
</tr>
<tr>
<td>autoplay</td>
<td>false</td>
<td>音频自动播放</td>
</tr>
<tr>
<td>theme</td>
<td>‘#b7daff’</td>
<td>主题色</td>
</tr>
<tr>
<td>loop</td>
<td>‘all’</td>
<td>音频循环播放, 可选值: ‘all’, ‘one’, ‘none’</td>
</tr>
<tr>
<td>order</td>
<td>‘list’</td>
<td>音频循环顺序, 可选值: ‘list’, ‘random’</td>
</tr>
<tr>
<td>preload</td>
<td>‘auto’</td>
<td>预加载，可选值: ‘none’, ‘metadata’, ‘auto’</td>
</tr>
<tr>
<td>volume</td>
<td>0.7</td>
<td>默认音量，请注意播放器会记忆用户设置，用户手动设置音量后默认音量即失效</td>
</tr>
<tr>
<td>audio</td>
<td>-</td>
<td>音频信息, 应该是一个对象或对象数组</td>
</tr>
<tr>
<td><a href="http://audio.name">audio.name</a></td>
<td>-</td>
<td>音频名称</td>
</tr>
<tr>
<td>audio.artist</td>
<td>-</td>
<td>音频艺术家</td>
</tr>
<tr>
<td>audio.url</td>
<td>-</td>
<td>音频链接</td>
</tr>
<tr>
<td>audio.cover</td>
<td>-</td>
<td>音频封面</td>
</tr>
<tr>
<td>audio.lrc</td>
<td>-</td>
<td><a href="https://aplayer.js.org/#/home?id=lrc">详情</a></td>
</tr>
<tr>
<td>audio.theme</td>
<td>-</td>
<td>切换到此音频时的主题色，比上面的 theme 优先级高</td>
</tr>
<tr>
<td>audio.type</td>
<td>‘auto’</td>
<td>可选值: ‘auto’, ‘hls’, ‘normal’ 或其他自定义类型, <a href="https://aplayer.js.org/#/home?id=mse-support">详情</a></td>
</tr>
<tr>
<td>customAudioType</td>
<td>-</td>
<td>自定义类型，<a href="https://aplayer.js.org/#/home?id=mse-support">详情</a></td>
</tr>
<tr>
<td>mutex</td>
<td>true</td>
<td>互斥，阻止多个播放器同时播放，当前播放器播放时暂停其他播放器</td>
</tr>
<tr>
<td>lrcType</td>
<td>0</td>
<td><a href="https://aplayer.js.org/#/home?id=lrc">详情</a></td>
</tr>
<tr>
<td>listFolded</td>
<td>false</td>
<td>列表默认折叠</td>
</tr>
<tr>
<td>listMaxHeight</td>
<td>-</td>
<td>列表最大高度</td>
</tr>
<tr>
<td>storageName</td>
<td>‘aplayer-setting’</td>
<td>存储播放器设置的 localStorage key</td>
</tr>
</tbody>
</table>
<p>例如:</p>
<div class="aplayer-wrap">
    <div id="aplayer3"><button class="docute-button load">点击加载播放器</div>
</div>
<pre><code class="language-js">const ap = new APlayer({
    container: document.getElementById('player'),
    mini: false,
    autoplay: false,
    theme: '#FADFA3',
    loop: 'all',
    order: 'random',
    preload: 'auto',
    volume: 0.7,
    mutex: true,
    listFolded: false,
    listMaxHeight: 90,
    lrcType: 3,
    audio: [
        {
            name: 'name1',
            artist: 'artist1',
            url: 'url1.mp3',
            cover: 'cover1.jpg',
            lrc: 'lrc1.lrc',
            theme: '#ebd0c2'
        },
        {
            name: 'name2',
            artist: 'artist2',
            url: 'url2.mp3',
            cover: 'cover2.jpg',
            lrc: 'lrc2.lrc',
            theme: '#46718b'
        }
    ]
});
</code></pre>
<h2 id="API"><a class="header-anchor" href="#API">¶</a>API</h2>
<ul>
<li>
<p><code>APlayer.version</code>: 静态属性, 返回 APlayer 的版本号</p>
</li>
<li>
<p><code>ap.play()</code>: 播放音频</p>
</li>
<li>
<p><code>ap.pause()</code>: 暂停音频</p>
</li>
<li>
<p><code>ap.seek(time: number)</code>: 跳转到特定时间，时间的单位为秒</p>
<pre><code class="language-js">ap.seek(100);
</code></pre>
</li>
<li>
<p><code>ap.toggle()</code>: 切换播放和暂停</p>
</li>
<li>
<p><code>ap.on(event: string, handler: function)</code>: 绑定音频和播放器事件，<a href="https://aplayer.js.org/#/home?id=event-binding">详情</a></p>
</li>
<li>
<p><code>ap.volume(percentage: number, nostorage: boolean)</code>: 设置音频音量</p>
<pre><code class="language-js">ap.volume(0.1, true);
</code></pre>
</li>
<li>
<p><code>ap.theme(color: string, index: number)</code>: 设置播放器主题色, index 默认为当前音频的 index</p>
<pre><code class="language-js">ap.theme('#000', 0);
</code></pre>
</li>
<li>
<p><code>ap.setMode(mode: string)</code>: 设置播放器模式，mode 取值应为 ‘mini’ 或 ‘normal’</p>
</li>
<li>
<p><code>ap.mode</code>: 返回播放器当前模式，‘mini’ 或 ‘normal’</p>
</li>
<li>
<p><code>ap.notice(text: string, time: number, opacity: number)</code>: 显示通知，时间的单位为毫秒，默认时间 2000 毫秒，默认透明度 0.8，设置时间为 0 可以取消通知自动隐藏</p>
<pre><code class="language-js">ap.notice('Amazing player', 2000, 0.8);
</code></pre>
</li>
<li>
<p><code>ap.skipBack()</code>: 切换到上一首音频</p>
</li>
<li>
<p><code>ap.skipForward()</code>: 切换到下一首音频</p>
</li>
<li>
<p><code>ap.destroy()</code>: 销毁播放器</p>
</li>
<li>
<p><code>ap.lrc</code></p>
<ul>
<li>
<p><code>ap.lrc.show()</code>: 显示歌词</p>
</li>
<li>
<p><code>ap.lrc.hide()</code>: 隐藏歌词</p>
</li>
<li>
<p><code>ap.lrc.toggle()</code>: 显示/隐藏歌词</p>
</li>
</ul>
</li>
<li>
<p><code>ap.list</code></p>
<ul>
<li>
<p><code>ap.list.show()</code>: 显示播放列表</p>
</li>
<li>
<p><code>ap.list.hide()</code>: 隐藏播放列表</p>
</li>
<li>
<p><code>ap.list.toggle()</code>: 显示/隐藏播放列表</p>
</li>
<li>
<p><code>ap.list.add(audios: array | object)</code>: 添加一个或几个新音频到播放列表</p>
</li>
</ul>
<pre><code class="language-js">ap.list.add([{
    name: 'name',
    artist: 'artist',
    url: 'url.mp3',
    cover: 'cover.jpg',
    lrc: 'lrc.lrc',
    theme: '#ebd0c2'
}]);
</code></pre>
<ul>
<li><code>ap.list.remove(index: number)</code>: 移除播放列表中的一个音频</li>
</ul>
<pre><code class="language-js">ap.list.remove(1);
</code></pre>
<ul>
<li><code>ap.list.switch()</code>: 切换到播放列表里的其他音频</li>
</ul>
<pre><code class="language-js">ap.list.switch(1);
</code></pre>
<ul>
<li><code>ap.list.clear()</code>: 清空播放列表</li>
</ul>
</li>
<li>
<p><code>ap.audio</code>: 原生 audio</p>
</li>
<li>
<p><code>ap.audio.currentTime</code>: 返回音频当前播放时间</p>
</li>
<li>
<p><code>ap.audio.duration</code>: 返回音频总时间</p>
</li>
<li>
<p><code>ap.audio.paused</code>: 返回音频是否暂停</p>
</li>
<li>
<p>支持大多数<a href="http://www.w3schools.com/tags/ref_av_dom.asp">原生audio接口</a></p>
</li>
</ul>
<h2 id="事件绑定"><a class="header-anchor" href="#事件绑定">¶</a>事件绑定</h2>
<p><code>ap.on(event, handler)</code></p>
<pre><code class="language-js">ap.on('ended', function () {
    console.log('player ended');
});
</code></pre>
<p>音频事件</p>
<ul>
<li>abort</li>
<li>canplay</li>
<li>canplaythrough</li>
<li>durationchange</li>
<li>emptied</li>
<li>ended</li>
<li>error</li>
<li>loadeddata</li>
<li>loadedmetadata</li>
<li>loadstart</li>
<li>mozaudioavailable</li>
<li>pause</li>
<li>play</li>
<li>playing</li>
<li>progress</li>
<li>ratechange</li>
<li>seeked</li>
<li>seeking</li>
<li>stalled</li>
<li>suspend</li>
<li>timeupdate</li>
<li>volumechange</li>
<li>waiting</li>
</ul>
<p>播放器事件</p>
<ul>
<li>listshow</li>
<li>listhide</li>
<li>listadd</li>
<li>listremove</li>
<li>listswitch</li>
<li>listclear</li>
<li>noticeshow</li>
<li>noticehide</li>
<li>destroy</li>
<li>lrcshow</li>
<li>lrchide</li>
</ul>
<h2 id="歌词"><a class="header-anchor" href="#歌词">¶</a>歌词</h2>
<p>我们有三种方式来给 APlayer 传递歌词，使用 <code>lrcType</code> 参数指明使用哪种方式，然后把歌词放到 <code>audio.lrc</code> 参数或者 HTML 里。</p>
<div class="aplayer-wrap">
    <div id="aplayer4"><button class="docute-button load">点击加载播放器</div>
</div>
<h3 id="LRC-文件方式"><a class="header-anchor" href="#LRC-文件方式">¶</a>LRC 文件方式</h3>
<p>第一种方式，把歌词放到 LRC 文件里，音频播放时会加载对应的 LRC 文件。</p>
<pre><code class="language-js">const ap = new APlayer({
    container: document.getElementById('aplayer'),
    lrcType: 3,
    audio: {
        name: 'name',
        artist: 'artist',
        url: 'demo.mp3',
        cover: 'demo.jpg',
        lrc: 'lrc.lrc'
    }
});
</code></pre>
<h3 id="JS-字符串方式"><a class="header-anchor" href="#JS-字符串方式">¶</a>JS 字符串方式</h3>
<p>第二种方式，把歌词放到 JS 字符串里面。</p>
<pre><code class="language-js">const ap = new APlayer({
    container: document.getElementById('aplayer'),
    lrcType: 1,
    audio: {
        name: 'name',
        artist: 'artist',
        url: 'demo.mp3',
        cover: 'demo.jpg',
        lrc: '[00:00.00]APlayer\n[00:04.01]is\n[00:08.02]amazing'
    }
});
</code></pre>
<h3 id="HTML-方式"><a class="header-anchor" href="#HTML-方式">¶</a>HTML 方式</h3>
<p>第三种方式，把歌词放到 HTML 里面。</p>
<pre><code class="language-html">&lt;link rel=&quot;stylesheet&quot; href=&quot;APlayer.min.css&quot;&gt;
&lt;div id=&quot;player&quot;&gt;
    &lt;pre class=&quot;aplayer-lrc-content&quot;&gt;
        [00:00.00]APlayer audio1
        [00:04.01]is
        [00:08.02]amazing
        &lt;!-- ... --&gt;
    &lt;/pre&gt;
    &lt;pre class=&quot;aplayer-lrc-content&quot;&gt;
        [00:00.00]APlayer audio2
        [00:04.01]is
        [00:08.02]amazing
        &lt;!-- ... --&gt;
    &lt;/pre&gt;
&lt;/div&gt;
&lt;script src=&quot;APlayer.min.js&quot;&gt;&lt;/script&gt;
</code></pre>
<pre><code class="language-js">const ap = new APlayer({
    container: document.getElementById('aplayer'),
    lrcType: 2,
    audio: [[
        {
            name: 'name1',
            artist: 'artist1',
            url: 'url1.mp3',
            cover: 'cover1.jpg'
        },
        {
            name: 'name2',
            artist: 'artist2',
            url: 'url2.mp3',
            cover: 'cover2.jpg'
        }
    ]]
});
</code></pre>
<h3 id="歌词格式"><a class="header-anchor" href="#歌词格式">¶</a>歌词格式</h3>
<p>支持下面格式的歌词：</p>
<p><code>[mm:ss]APlayer</code></p>
<p><code>[mm:ss.xx]is</code></p>
<p><code>[mm:ss.xxx]amazing</code></p>
<p><code>[mm:ss.xx][mm:ss.xx]APlayer</code></p>
<p><code>[mm:ss.xx]&lt;mm:ss.xx&gt;is</code></p>
<p><code>[mm:ss.xx]amazing[mm:ss.xx]APlayer</code></p>
<h2 id="播放列表"><a class="header-anchor" href="#播放列表">¶</a>播放列表</h2>
<p>当有多个音频时会 APlayer 会展示一个播放列表，<code>listFolded</code> 参数指明列表是否默认折叠，<code>listMaxHeight</code> 参数指明列表最大高度。</p>
<div class="aplayer-wrap">
    <div id="aplayer5"><button class="docute-button load">点击加载播放器</div>
</div>
<pre><code class="language-js">const ap = new APlayer({
    container: document.getElementById('player'),
    listFolded: false,
    listMaxHeight: 90,
    lrcType: 3,
    audio: [
        {
            name: 'name1',
            artist: 'artist1',
            url: 'url1.mp3',
            cover: 'cover1.jpg',
            lrc: 'lrc1.lrc',
            theme: '#ebd0c2'
        },
        {
            name: 'name2',
            artist: 'artist2',
            url: 'url2.mp3',
            cover: 'cover2.jpg',
            lrc: 'lrc2.lrc',
            theme: '#46718b'
        }
    ]
});
</code></pre>
<h2 id="吸底模式"><a class="header-anchor" href="#吸底模式">¶</a>吸底模式</h2>
<p>APlayer 可以通过吸底模式固定在页面底部，这种模式跟普通模式有很大不同。</p>
<div class="aplayer-wrap">
    <div id="aplayer9"><button class="docute-button load">点击加载播放器</div>
</div>
<pre><code class="language-js">const ap = new APlayer({
    container: document.getElementById('player'),
    fixed: true,
    audio: [{
        name: 'name',
        artist: 'artist',
        url: 'url.mp3',
        cover: 'cover.jpg',
    }]
});
</code></pre>
<h2 id="迷你模式"><a class="header-anchor" href="#迷你模式">¶</a>迷你模式</h2>
<p>如果你没有足够空间来放置正常模式的播放器，那么你可以考虑使用迷你模式。</p>
<p>请注意迷你模式与吸底模式冲突。</p>
<div class="aplayer-wrap">
    <div id="aplayer6"><button class="docute-button load">点击加载播放器</div>
</div>
<pre><code class="language-js">const ap = new APlayer({
    container: document.getElementById('player'),
    mini: true,
    audio: [{
        name: 'name',
        artist: 'artist',
        url: 'url.mp3',
        cover: 'cover.jpg',
    }]
});
</code></pre>
<h2 id="MSE-支持"><a class="header-anchor" href="#MSE-支持">¶</a>MSE 支持</h2>
<h3 id="HLS"><a class="header-anchor" href="#HLS">¶</a>HLS</h3>
<p>需要在 <code>APlayer.min.js</code> 前面加载 <a href="https://github.com/video-dev/hls.js">hls.js</a>。</p>
<div class="aplayer-wrap">
    <div id="aplayer7"><button class="docute-button load">点击加载播放器</div>
</div>
<pre><code class="language-html">&lt;link rel=&quot;stylesheet&quot; href=&quot;APlayer.min.css&quot;&gt;
&lt;div id=&quot;aplayer&quot;&gt;&lt;/div&gt;
&lt;script src=&quot;hls.min.js&quot;&gt;&lt;/script&gt;
&lt;script src=&quot;APlayer.min.js&quot;&gt;&lt;/script&gt;
</code></pre>
<pre><code class="language-js">const ap = new APlayer({
    container: document.getElementById('aplayer'),
    audio: [{
        name: 'HLS',
        artist: 'artist',
        url: 'url.m3u8',
        cover: 'cover.jpg',
        type: 'hls'
    }]
});
</code></pre>
<pre><code class="language-js">// 另一种方式，使用 customAudioType
const ap = new APlayer({
    container: document.getElementById('aplayer'),
    audio: [{
        name: 'HLS',
        artist: 'artist',
        url: 'url.m3u8',
        cover: 'cover.jpg',
        type: 'customHls'
    }],
    customAudioType: {
        'customHls': function (audioElement, audio, player) {
            if (Hls.isSupported()) {
                const hls = new Hls();
                hls.loadSource(audio.url);
                hls.attachMedia(audioElement);
            }
            else if (audioElement.canPlayType('application/x-mpegURL') || audioElement.canPlayType('application/vnd.apple.mpegURL')) {
                audioElement.src = audio.url;
            }
            else {
                player.notice('Error: HLS is not supported.');
            }
        }
    }
});
</code></pre>
<h2 id="根据封面自适应主题色"><a class="header-anchor" href="#根据封面自适应主题色">¶</a>根据封面自适应主题色</h2>
<p>需要额外加载 <a href="https://github.com/lokesh/color-thief/blob/master/src/color-thief.js">color-thief.js</a></p>
<div class="aplayer-wrap">
    <div id="aplayer8"><button class="docute-button load">点击加载播放器</div>
</div>
<pre><code class="language-html">&lt;link rel=&quot;stylesheet&quot; href=&quot;APlayer.min.css&quot;&gt;
&lt;div id=&quot;aplayer&quot;&gt;&lt;/div&gt;
&lt;script src=&quot;APlayer.min.js&quot;&gt;&lt;/script&gt;
&lt;script src=&quot;color-thief.js&quot;&gt;&lt;/script&gt;
</code></pre>
<pre><code class="language-js">const ap = new APlayer({
    container: document.getElementById('aplayer'),
    theme: '#e9e9e9',
    audio: [{
        name: 'name1',
        artist: 'artist1',
        url: 'url1.mp3',
        cover: 'cover1.jpg'
    }, {
        name: 'name2',
        artist: 'artist2',
        url: 'url2.mp3',
        cover: 'cover2.jpg'
    }]
});

const colorThief = new ColorThief();
const image = new Image();
const xhr = new XMLHttpRequest();
const setTheme = (index) =&gt; {
    if (!ap.list.audios[index].theme) {
        xhr.onload = function(){
            let coverUrl = URL.createObjectURL(this.response);
            image.onload = function(){
                let color = colorThief.getColor(image);
                ap.theme(`rgb(${color[0]}, ${color[1]}, ${color[2]})`, index);
                URL.revokeObjectURL(coverUrl)
            };
            image.src = coverUrl;
        }
        xhr.open('GET', ap.list.audios[index].cover, true);
        xhr.responseType = 'blob';
        xhr.send();
    }
};
setTheme(ap.list.index);
ap.on('listswitch', (index) =&gt; {
    setTheme(index);
});
</code></pre>
<h2 id="CDN"><a class="header-anchor" href="#CDN">¶</a>CDN</h2>
<ul>
<li><a href="https://www.jsdelivr.com/package/npm/aplayer">jsDelivr</a></li>
<li><a href="https://cdnjs.com/libraries/aplayer">cdnjs</a></li>
<li><a href="https://unpkg.com/aplayer/">unpkg</a></li>
</ul>
<h2 id="常见问题"><a class="header-anchor" href="#常见问题">¶</a>常见问题</h2>
<h3 id="为什么播放器不能在手机上自动播放？"><a class="header-anchor" href="#为什么播放器不能在手机上自动播放？">¶</a>为什么播放器不能在手机上自动播放？</h3>
<p>大多数移动端浏览器禁止了音频自动播放。</p>