jPlayer音视频播放器插件

简介

jPlayer 是一个基于 jQuery 的开源音频/视频播放器插件，通过 HTML5 + Flash 双引擎实现跨浏览器兼容，支持自定义皮肤与丰富的 API，曾广泛应用于老项目的音乐播放、视频展示场景（目前新项目更推荐 video.js、hls.js 等现代方案）。

支持的平台与浏览器

Windows: Firefox, Chrome, Opera, Safari, IE6, IE7, IE8, IE9

OSX: Safari, Firefox, Chrome, Opera

iOS: Mobile Safari: iPad, iPhone, iPod Touch

Android: Android 2.3 Browser

Blackberry: We require a device for testing

媒体支持

HTML5: mp3, mp4 (AAC/H.264), ogg (Vorbis/Theora), webm (Vorbis/VP8), wav

Flash: mp3, mp4 (AAC/H.264)

---

一、核心特性

• ✅ 双引擎兼容：优先使用 HTML5，不支持的浏览器（如 IE8-）自动降级为 Flash
• ✅ 多格式支持：音频支持 MP3、OGG、WAV；视频支持 MP4（H.264）、OGG、WebM
• ✅ 完全自定义：无默认 UI，可通过 HTML/CSS 自由设计控制条、皮肤
• ✅ API 丰富：提供播放、暂停、进度、音量等全流程控制方法与事件回调
• ✅ 轻量开源：MIT 协议，可免费商用，核心文件仅 20KB+
• ✅ 老浏览器友好：兼容 IE6+、Chrome、Firefox、Safari 等全系列浏览器

---

二、快速上手

1. 依赖与安装

jPlayer 依赖 **jQuery 1.7+**，需先引入 jQuery，再引入 jPlayer 核心文件。

方式1：CDN 引入（推荐）

<!-- 1. 引入 jQuery -->
<script src="https://unpkg.com/jquery@3.7.1/dist/jquery.min.js"></script>
<!-- 2. 引入 jPlayer 核心 CSS（可选，用于基础布局） -->
<link rel="stylesheet" href="https://unpkg.com/jplayer@2.9.2/dist/skin/blue.monday/css/jplayer.blue.monday.min.css">
<!-- 3. 引入 jPlayer 核心 JS -->
<script src="https://unpkg.com/jplayer@2.9.2/dist/jplayer/jquery.jplayer.min.js"></script>
<!-- 4. 引入 Flash  fallback 文件（可选，用于老浏览器） -->
<!-- 需下载 jPlayer 源码，将 `swf` 文件夹放到项目中 -->

方式2：npm 安装

npm install jplayer --save

2. 基础 HTML 结构

jPlayer 需要两个核心容器：

• #jquery_jplayer：隐藏的媒体播放容器（用于加载音频/视频）
• #jp_container：自定义 UI 容器（控制条、播放按钮等）

<!-- 1. 隐藏的媒体容器 -->
<div id="jquery_jplayer"></div>

<!-- 2. 自定义 UI 容器（以 blue.monday 皮肤为例） -->
<div id="jp_container" class="jp-audio">
  <div class="jp-type-single">
    <div class="jp-gui jp-interface">
      <!-- 播放/暂停按钮 -->
      <div class="jp-controls">
        <button class="jp-play">播放</button>
        <button class="jp-pause">暂停</button>
      </div>
      <!-- 进度条 -->
      <div class="jp-progress">
        <div class="jp-seek-bar">
          <div class="jp-play-bar"></div>
        </div>
      </div>
      <!-- 音量控制 -->
      <div class="jp-volume-controls">
        <button class="jp-mute">静音</button>
        <button class="jp-unmute">取消静音</button>
        <div class="jp-volume-bar">
          <div class="jp-volume-bar-value"></div>
        </div>
      </div>
      <!-- 时间显示 -->
      <div class="jp-time-holder">
        <span class="jp-current-time"></span> / <span class="jp-duration"></span>
      </div>
    </div>
  </div>
</div>

3. 初始化

$(document).ready(function() {
  // 初始化 jPlayer
  $('#jquery_jplayer').jPlayer({
    // 1. 核心配置
    ready: function() {
      // 播放器准备完成后设置媒体文件
      $(this).jPlayer('setMedia', {
        mp3: 'https://example.com/audio.mp3', // MP3 格式（必填）
        oga: 'https://example.com/audio.ogg'  // OGG 格式（可选，兼容 Firefox）
      });
    },
    // 2. 格式支持
    supplied: 'mp3,oga', // 支持的音频格式（逗号分隔）
    // 3. Flash fallback 配置（老浏览器用）
    swfPath: '/path/to/swf', // Flash 文件路径（swf 文件夹所在目录）
    solution: 'html,flash',  // 优先 HTML5，不行用 Flash
    // 4. UI 配置
    autoPlay: false,         // 自动播放
    loop: false,             // 循环播放
    volume: 0.8,             // 初始音量（0-1）
    // 5. 绑定 UI 容器
    cssSelectorAncestor: '#jp_container',
    // 6. 事件回调
    play: function() {
      console.log('开始播放');
    },
    pause: function() {
      console.log('暂停播放');
    },
    ended: function() {
      console.log('播放结束');
    }
  });
});

---

三、配置详解

1. 核心配置

配置项	类型	默认值	说明
ready	Function	null	播放器准备完成后的回调函数（必须在此设置媒体文件）
setMedia	Object	null	媒体文件配置（通过方法调用，见下文），格式：{mp3: '...', oga: '...', m4a: '...'}
supplied	String	''	支持的媒体格式（逗号分隔），音频：mp3,oga,wav,m4a；视频：m4v,ogv,webm
solution	String	'html,flash'	引擎优先级：'html,flash'（先 HTML5 后 Flash）或 'flash,html'
swfPath	String	'js'	Flash 文件（Jplayer.swf）所在目录的相对/绝对路径
wmode	String	'window'	Flash 窗口模式：'window'/'opaque'/'transparent'（解决 Flash 遮挡问题用 'opaque'）

2. UI 与行为配置

配置项	类型	默认值	说明
autoPlay	Boolean	false	是否自动播放（注意：现代浏览器通常禁止自动播放带声音的媒体）
loop	Boolean	false	是否循环播放
volume	Number	0.8	初始音量（0-1，1 为最大）
muted	Boolean	false	是否初始静音
preload	String	'metadata'	预加载策略：'none'（不预加载）/'metadata'（仅预加载元数据）/'auto'（预加载整个文件）
cssSelectorAncestor	String	''	UI 容器的选择器（如 '#jp_container'），用于绑定控制条
cssSelector	Object	{}	自定义 UI 元素的选择器（覆盖默认绑定），如：{play: '.my-play-btn', pause: '.my-pause-btn'}
toggleDuration	Boolean	false	点击时间显示是否切换“当前时间/剩余时间”

3. 事件回调配置

配置项	说明	回调参数
ready	播放器准备完成	event
setmedia	设置媒体文件后	event
play	开始播放时	event
pause	暂停播放时	event
ended	播放结束时	event
timeupdate	播放进度更新时（频繁触发）	event
volumechange	音量变化时	event
error	播放出错时	event
waiting	缓冲等待时	event
playing	缓冲结束继续播放时	event

---

四、常用方法

初始化后可通过 $('#jquery_jplayer').jPlayer('方法名', 参数) 调用：

1. 媒体控制

// 设置/更换媒体文件
$('#jquery_jplayer').jPlayer('setMedia', {
  mp3: 'https://example.com/new-audio.mp3',
  oga: 'https://example.com/new-audio.ogg'
});

// 播放
$('#jquery_jplayer').jPlayer('play');

// 暂停
$('#jquery_jplayer').jPlayer('pause');

// 停止（暂停并重置进度到0）
$('#jquery_jplayer').jPlayer('stop');

// 跳转到指定位置（单位：秒）
$('#jquery_jplayer').jPlayer('play', 30); // 从第30秒开始播放

2. 音量控制

// 设置音量（0-1）
$('#jquery_jplayer').jPlayer('volume', 0.5);

// 静音
$('#jquery_jplayer').jPlayer('mute');

// 取消静音
$('#jquery_jplayer').jPlayer('unmute');

3. 其他方法

// 重新加载媒体文件
$('#jquery_jplayer').jPlayer('load');

// 销毁播放器（释放资源）
$('#jquery_jplayer').jPlayer('destroy');

// 获取当前播放时间（秒）
const currentTime = $('#jquery_jplayer').data('jPlayer').status.currentTime;

// 获取媒体总时长（秒）
const duration = $('#jquery_jplayer').data('jPlayer').status.duration;

---

五、注意事项

1. jQuery 依赖：必须先引入 jQuery，且版本需 ≥ 1.7（推荐 jQuery 3.x）。
2. Flash 路径：老浏览器需 Flash fallback，务必正确设置 swfPath（指向 Jplayer.swf 所在目录）。
3. 格式兼容性：
   • 音频：优先用 MP3（全浏览器支持），补充 OGG（兼容旧版 Firefox）；
   • 视频：优先用 MP4（H.264），补充 OGV/WebM（兼容旧版 Firefox/Chrome）。
4. 自动播放限制：现代浏览器（Chrome、Safari 等）禁止自动播放带声音的媒体，需用户交互后才能播放。

---

六、总结

jPlayer 已停止维护（最后更新于 2019 年），仅推荐用于老项目维护；新项目建议使用 video.js（视频）、howler.js（音频）等现代方案。