audiojs完整入门:3行代码让HTML5 audio标签实现跨浏览器MP3播放

原创2026-11-11 20:17:391,180 阅读

audiojs完整入门:3行代码让HTML5 audio标签实现跨浏览器MP3播放

audiojs 是一个轻量的 JavaScript 封装库,它让 HTML5 <audio> 标签可以在任意浏览器中播放 MP3。在浏览器原生支持 audio 时直接使用原生播放器,不支持时自动回退到隐藏的 Flash 播放器,并给所有浏览器提供统一的、可用 CSS 自定义的播放器界面。对于需要"跨浏览器 MP3 播放"的前端项目来说,它是最简单的 HTML5 audio fallback 方案。

audiojs 是什么:HTML5 audio 标签的跨浏览器封装

传统 HTML5 <audio> 标签在不同浏览器中支持情况参差不齐,老版本 IE 等浏览器完全无法播放 MP3。audiojs 的解决思路非常直接:

  • 原生优先:浏览器支持 <audio> 播放 MP3 时,直接走原生能力(源码见 audiojs/audio.js 中的 useFlash 检测逻辑)
  • Flash 兜底:检测到不支持时,自动注入一个 1x1 像素的隐藏 SWF 来模拟播放
  • 统一 UI:动态注入一套默认播放器样式(播放/暂停按钮、进度条、时间显示),所有浏览器看到的效果一致
  • 纯 JS 单文件:核心逻辑全部集中在 audiojs/audio.js(约 700 行,附带完整注释),无其他依赖

注意:audiojs 只播放 MP3,不播放 OGG。官方说明见 README.md。

快速上手:audiojs 安装与文件准备

只需 3 个文件,且必须放在同一目录:

文件 作用
audiojs/audio.js 核心 JS 逻辑(也可用压缩版 audiojs/audio.min.js)
audiojs/audiojs.swf Flash 回退播放器
audiojs/player-graphics.gif 播放/暂停/加载按钮的精灵图

库会自动根据 audio.js 的路径推断 swf 和图片位置(见 audiojs/audio.js 中的 path 变量),所以三者放同一文件夹即可,无需额外配置。

3 行核心代码:audiojs 初始化教程

初始化只需引入脚本 + 一行 createAll(),官方首页 index.html 就是完整写法:

<script src="/audiojs/audio.js"></script>
<script>
  audiojs.events.ready(function() {
    var as = audiojs.createAll();
  });
</script>

然后在页面任意位置写上普通的 audio 标签:

<audio src="/mp3/juicy.mp3" preload="auto"></audio>

createAll() 会自动扫描页面中所有 <audio> 标签,为每个生成一个播放器实例(见 audiojs/audio.js)。audiojs.events.ready 内置了跨浏览器的 DOM ready 处理,所以不需要 $(document).ready 之类的封装。

也可以用 audiojs.create(element, options) 只初始化某一个元素,适合动态渲染的场景:

var audios = document.getElementsByTagName('audio');
var a1 = audiojs.create(audios[0], { css: false });

常用属性与播放器选项

原生属性:preload、loop、autoplay

audiojs 完整支持 <audio> 标签的标准属性,对应示例见 demos/test3.html:

<audio src="song.mp3" preload="none"></audio>   <!-- 不预加载 -->
<audio src="song.mp3" autoplay></audio>          <!-- 自动播放 -->
<audio src="song.mp3" loop></audio>              <!-- 循环播放 -->

自定义外观:CSS 类名与默认样式

默认深色播放器样式内嵌在 JS 中(audiojs/audio.js),想完全自定义外观时,可以关闭内置 CSS 并传入自己的 class 名。完整示例见 demos/test2.html:

audiojs.create(audios[0], {
  css: false,               // 关闭默认样式
  createPlayer: {
    playPauseClass: 'play-pauseZ',
    scrubberClass: 'scrubberZ',
    progressClass: 'progressZ',
    timeClass: 'timeZ'
    // ...
  }
});

这样就能用任意 CSS 把播放器改成红白、圆角、横条等任何风格,是 audiojs 自定义播放器样式的标准做法。

音量控制:setVolume 方法

每个播放器实例都暴露了 play()、pause()、setVolume()、skipTo() 等 API,音量控制示例见 demos/test6.html:

var as = audiojs.createAll();
audio.setVolume(0.5);  // 音量范围 0~1

示例演示与资源文件

仓库自带 6 个渐进式 demo,非常适合作为 audiojs 源码学习路径:

演示用的 MP3 资源在 mp3/ 目录,共 9 首 Creative Commons 授权的 Bensound 曲目(如 mp3/bensound-buddy.mp3),可直接用于本地测试。

常见问题 FAQ

Q:audiojs 还需要用吗? 现代浏览器已基本全面支持 MP3 播放,新项目通常直接写 <audio> 即可。但 audiojs 的价值在于:为老浏览器兜底 + 提供一套统一的 UI,且 3 个文件零依赖,适合需要兼容旧环境或希望"一个标签搞定"的场景。它也可以通过 bower install audiojs 安装。

Q:加载失败会怎样? 播放器会显示错误状态并提示 Error loading: "xxx.mp3",同时提供下载链接(回调见 audiojs/audio.js 的 loadError),不会导致页面 JS 报错。

Q:支持移动端吗? 支持。源码中对 iOS 的预加载限制做了专门处理(audiojs/audio.js 的 trackLoadProgress),移动端首次点击播放按钮后开始加载。

小结

audiojs 用不到 3 行初始化代码,就补齐了 HTML5 audio 标签的跨浏览器播放短板:原生支持时零开销,不支持时 Flash 兜底,UI 统一且可用 CSS 完全定制。如果你正在找一个"HTML5 audio 跨浏览器 MP3 播放器"的最简方案,它就是答案。更多说明可参考 README.md 与 index.html。

登录后查看全文
audiojs