jPlayer使用指南
1. jPlayer基础
1\ FLASH安全规则
a. jPlay插件的SWF文件必须要在你的域内,子域与主域被视为不同域.也不要从happyworm.com网站(就是提供这个插件的网站)来链接这些SWF文件.你需要把这些文件上传到你的域下的js目录中,如果需要的话,也可以通过创建选项swfPath来更改路径.
下面作者开始吐槽: 从技术上讲,你是可以从他的happyworm.com网站上链接一些JS文件,但你的网站中必须要有一个Jplayer.swf.当然作者不建议你这么干,因为他们的资源是有限的,架不住啊.
b. 在本地运行jPlayer会生成FLASH安全问题,你需要通过FLASH SETTINGS MANAGER来解决这个问题.有兴趣去仔细看看啊.
2\ MP3编码
a. 因为有些浏览器使用jPlayer的FLASH元素,所有要播放的MP3文件必须要根据浏览器的ADOBE FLASH插件的限制来编码.
1. Constant Bitrate Encoded, 不变比特编码,
2. Sample Rate: 样本率(在计算机或通信系统的音频开发中，采样频率指每秒收集的用于数字化代表事件的声音采样的个数), 11,0025Hz的倍数,如22,050Hz and 44,100Hz都是可用的采样率.
3\ 应用服务针对MP3/OGG的响应
a. 你的域服务必须要对MP3/OGG的正确响应,即
1. MP3文件必须要有audio/mpeg或者application/octet-stream的内容类型(MIME Type);
2. OGG文件必须要有application/ogg的内容类型(MIME Type);
3. Content-Encoding: gzip,(许多要求标头字段可让客户端在值的部份指定数个可接受的选项，而且在某些情况中，甚至可以指定每一个选项的喜好等级。多个项目可使用逗号来区隔。例如，客户端可以传送包括 "Content-Encoding:gzip, compress" 的要求标头，指出它将接受任一种压缩类型。如果服务器对响应本文使用 gzip 编码方式，则它的响应标头将包括 "Content-Encoding:gzip") , 是不可以的,因为Adobe Flash Plugin会挂掉.
4\ 如何顺手干掉jPlayer呢?
a. 因为jPlayer在一些浏览器中使用FLASH,所以jPlayer所在的层,是不能隐藏的,别把它所在层的CSS属性display:none,那就真的none了.还有jPlay自己负责处理自己的CSS样式,因此把它的CSS与你的CSS定义文件分开.
b. 除了这些还要小心使用任何jQuery的动画函数, 像什么fadeIn(), fadeOut()之类,是不针能对jPlay所在层或所在层的父节点耍的.
2. jPlay构造器,$(id).jPlayer( Object: options ) : jQuery.
1\描述;
a. jPlay构造器当你给定一个id后,就会使用你提供的选项(如果有的话)创建了. jPlay使用的层必须要是空的,并且其它的什么猫猫狗狗的应用都不能使用.作者又很贴心的提示,如果你觉得为难,就把它放到<body>中的顶层元素吧,这样jPlay的操作就不会被其它什么最讨厌的干扰了.
b. 注意啊,最重要的选项是ready项, 这个项呢定义了当jPlay一旦可用时做什么. 在ready()被调用之前,试图向jPlay发送什么命令的,必将导致运行时错误,那是无疑的.
c. 还有下一个最重要的选项就是swfPath了, 定义了jPlayer SWF文件的位置,记得哦,把这个SWF文件上传到你的服务器中,再次强调.
2\ 参数
a. 选项:
1. ready: 函数(默认: function(){}),定义了一个当jPlay插件可用时调用的函数. 为了引用当前实例,请使用this.element.一般情况下推荐,this.element.jPlayer("setFile",mp3),为jPlay指定一个将要使用的可用MP3文件.//这个函数啊,是用来消除javascript代码与flash代码之间的竞争的,确保了javascript代码执行时,flash函数定义都到位了.
2. swfPaht: 字符串:(默认: "js"), 定义jPlayer SWF文件的相对或绝路径//这样就为开发者提供了一个可选的SWF存放路径,当然URL要以标准的URL编码方式,并且对于反斜杠不依赖,"myPath/"="myPath"
3. volume: 数字:(默认: 80), 按百分比定义音量.
4. oggSupport: 布尔:(默认: false), 对于OGG格式浏览器,在HTML5中OGG支持使能.//这样开发者就可以为每个MP3文件定义一个对应的可选OGG文件.
5. nativeSupport: 布尔:(默认: true), 在HTML5中对于本地音频支持使能.//如果将其值设置为false,将允许开发者强迫jPlay使用FLASH组件,在html5浏览器上开发时,这个选项对于测试swfPath是否正常很有用,这家伙是念念不忘swfPath啊,警告,嗯,有些mobile浏览器不支持FLASH,但支持HTML5.
6. customCssIds: 布尔:(默认: false), 默认时jPlay使用预先定的cssIds集合, 如果将这个值设为true,就取消了与默认ID们的关联,开发者可以自己定义一套CSS id,那我直是没事干了,闲得.
7. graphicsFix: 布尔:(默认: true), 图像更新处理,这个对于Safari和Chrome浏览器来说特别有用，它能对一个被移出屏幕之外的<div>中写入一个随机数，我怎么没看出来有什么特别用．//jPlay项目如果没用进度条的话,可把这个值设成false,警告,屏幕阅读器(大概指能电子发声阅读之类的工具)可能试图把这个随机数读出来,注意用的是loud有喜感.
8. cssPrefix: 字符串:(默认: "jqjp"),极品极品? 对于jPlay内部生成的HTML代码定义的ID前缀. //作者说如果你有命名冲突的话这个很管用,但是作者也承认一般人不会这么无聊.
9. errorAlerts: 布尔:(默认: false), 通过alerts发出致命错误报告. //作者偷偷地说,如果这项使能的话,不得了,能帮你debug项目哦.
10. warningAlerts 布尔:(默认: false), 与上述差不多.报告警告.
11. position: 字符串:(默认: absolute), left: 字符串:(默认: 0), top: 字符串:(默认: 0),width: 字符串:(默认: 0), height: 字符串:(默认: 0),bgcolor: 字符串:(默认: #fffff),六个css属性的定义.
12. quality:字符串:(默认: high): 定义FLASH的播放质量.
3\ 一些例子:
a. 先来个HTML的框架
<head>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"> //链接的jquery的js文件
</script>
<script type="text/javascript" src="js/jquery.jplayer.js">//主角出场
</script>
<script>
$(document).ready(function() { }); //玩活的地方
</script>
</head>
<body>
<div id="jpId"></div> //为播放器准备的层,按作者的教导这个层可不能hidden的
</body>
b. 例子1: 开始初始化jPlayer
$(document).ready(function() {
$("#jpId").jPlayer( { //先要引用存放播放器的层
ready: function () {//ready属性的设置
this.element.jPlayer("setFile", "../mp3/elvis.mp3"); // 定义mp3文件,
}
});
});
c. 例子2: 开始初始化jPlayer
$("#jpId").jPlayer( {
ready: function () {
this.element.jPlayer("setFile", "mp3/elvis.mp3", "ogg/elvis.ogg"); //定义mp3文件及对应的ogg文件
},
oggSupport: true,//ogg文件支持使能
swfPath: "http://www.myDomain.com/jPlayer/js"//设置作者宝贵的SWF文件路径.
});
d. 例子3: 开始初始化jPlayer
$("#jpId").jPlayer( {
ready: function () {
this.element.jPlayer("setFile", "http://www.myDomain.com/mp3/elvis.mp3").jPlayer("play"); // 设置初始化成功后播放的mp3文件,且自动就播放了
},
swfPath: "jPlayer/js" //设置作者宝贵的SWF文件路径.
});
d. 例子4: 觉得前面初始化例子太简单的话,那么下面的例子就高级一些了,反正我没感觉高级在哪里.
$("#jpId").jPlayer( {
ready: function () {
// 直接调用该实例的jPlayer方法(但如果这么干,就不能支持jQuery宝贵的连缀操作了)
this.setFile("mp3/elvis.mp3", "ogg/elvis.ogg"); // 定义mp3及相应的ogg文件
this.play(); // 自动播放
},
oggSupport: true//使能ogg支持
});
e. 例子5: 一个坏例子,
$("#jpId").jPlayer( {
ready: function () {
this.element.jPlayer("setFile", "elvis.mp3");
}
});
$("#jpId").jPlayer("play"); // 杯具发生的原因在于,这个PLAY放在ready之外,因此还没准备好就开播,会挂的.
3. jPlay方法:jPlay的控制是通过向$(id).jPlayer()的插件方法发送方法名来实现的.
a. $(id).jPlayer( "cssId", String: methodName, String: methodCssId ) : jQuery
该cssId方法,是用来创建jPlay与网页上的CSS元素之间关联关系的.比如说,把一个网页上的按键图片与播放命令相关联,对于这个方法本人表示甚慰.比较方便啊,默认的情况下,jPlay使用一个预定义的cssId集合,当然也可以通过设置customCssIds为真来改变他,好吧我承认我上面说错了.此外,一个jPlay方法只能关联一个cssID,新的关联会自动取消老的.上面的调用形式中methodCssId指的是要关联的cssID,methodName即方法名,那么有哪些方法名呢,开始,:
1. play=显然是播放mp3的方法, 2. pause=显然是暂停mp3的方法, 3. stop=显然是停止mp3的方法
4. loadBar=监视与操纵装载进程条 5. playBar=播放进度条 6. volumeMin=最小音量
7. volumeMax=最大音量 8. volumeBar=监听音量条 9. volumeBarValue=操作音量值.
一个小例子:
$(document).ready(function() {
$("#jpId").jPlayer( {
ready: function () {
this.element.jPlayer("setFile", "mp3/elvis.mp3");
},
customCssIds: true
})
.jPlayer( "cssId", "play", "thePlayButton" )
.jPlayer( "cssId", "loadBar", "theLoadBar" );
});
b. $(id).jPlayer( "setFile", String: mp3, [String: ogg] ) : jQuery
该方法是用来定义要播放的文件, mp3文件是强制要的,后面的ogg则不一定.当然如果你要的话,显然要在初始化jPlay时要把ogg支持使能,但是如果这个使能的话,对不住mp3,ogg那都是一定要的.我实在忍不住了,查了下ogg是什么东西,如下(Ogg是一种先进的有损的音频压缩技术，正式名称是Ogg Vorbis，是一种免费的开源音频格式。OGG编码格式远比90年代开发成功的MP3先进，它可以在相对较低的数据速率下实现比MP3更好的音质。)平静一下心情,go on.
这个方法一定要在jPlay其它方法调用之前使用,比如.jPlayer("play")方法,那是当然的,我们都是讲理的人嘛.此外,本插件在setFile方法调用时是不会下载新文件的,且此命令一发,不得了,任何正在播放的小曲儿都会被停止并且下载也会取消.
如果{nativeSupport: true}被设了,jPlayer将使用html5解决方案,如果有的话,没有就使用flash播放,{nativeSupport: false}设置,则大家一律用Flash,如果{oggSupport: true}被设的话, OGG文件就一定会被那些支持HTML5浏览器播放了,羡慕ing...,其它就用MP3基于HTML5或者FLASH凑合了.总之{nativeSupport: true}与{oggSupport: true}结合的话,优先权是这样的: HTML5 > Flash 且 OGG > MP3, 就这样的.
参数: mp3: mp3文件,可以定义URL或文件名, ogg: ogg文件,可以定义URL或文件名.
例子很简单不写了.
c. $(id).jPlayer( "clearFile" ) : jQuery
该方法用来清除声音文件并停止放音,如果有声音文件正在下载的话,下载也会取消的.这个命令一发,一些播放命令,如jPlayer("play")之类的全歇菜了,除非有新文件通过setFile来设置,才管用.参数就是没有参数.
d. $(id).jPlayer( "play" ) : jQuery
该方法即是播放了,如果必要的话会开始下载文件哦.播放会从mp3开始的地方,或者上次暂停的地方开始.参数就是没有.
e. $(id).jPlayer( "pause" ) : jQuery
该方法即是暂停了,如果暂停的话,下次播放开始的地方会存在插件中的,厉害吧.也没有参数.
f. $(id).jPlayer( "stop" ) : jQuery
该方法即停止了,播放的位置会恢复到歌子开始的地方.如果在setfile命令之后,光速地使用该方法,并且浏览器使用HTML5 audio的话,这个命令一开始会当掉,不过不要紧,会有一个内部的计时器每隔100S不断地测试命令直到成功.没有参数
g. $(id).jPlayer( "playHead", Number: percentOfLoaded ) : jQuery
这个方法将当前的播放地点移到某个新地方,最初的用法是插件内部用来响应在下载进度条上的点击,然后把播放位置放在新位置,并且如果在setfile命令之后,光速地使用...,同上,参数是percentOfLoaded, 0-100,不过有一点千万要搞清的.这个比例可不是与整个mp3文件大小相比,而是针对当前下载的文件量比较,比如说当前下载量为整个文件的50%,而percentOfLoaded设为50%,那么当前播放的位置会移到整个文件的25%.
h. $(id).jPlayer( "playHeadTime", Number: playedTime ) : jQuery
这个方法是将播放位置移到新的位置,定义是毫秒单位,并且如果在setfile命令之后,光速地使用...,同上,参数,playedTime播放位置相对于歌子开始处的毫秒数.如果歌儿正在下载,那么播放会耐心地等待到下载那个点时才开始.
i. $(id).jPlayer( "volume", Number: percent ) : jQuery
这个方法是控制音量的.参数是与最大音量的比较值.静是0, 中间是50,最大100, 此外还有:$(id).jPlayer( "volumeMin" ) : jQuery这个是静音,$(id).jPlayer( "volumeMax" ) : jQuery,这个是最大.都没有参数.
j. $(id).jPlayer( "onSoundComplete", Function: endOfSong ) : jQuery
这个方法用来定义一个回调函数,当歌儿放完后调用. 参数就是endOfSong函数名.
两个例子:
$("#jpId").jPlayer("onSoundComplete", function() { this.element.jPlayer("play"); // 自动重放});
$("#jpId").jPlayer("onSoundComplete", function() { this.play(); // 直接调用jPlay实例的方法,不支持连缀哦, // 自动重放});
k. $(id).jPlayer( "onProgressChange", Function: handleChanges ) : jQuery
这个方法用来定义一个函数, 可接收五个参数,每次插件更新下载进度条或播放进度条时调用,在mp3(或ogg)文件播放时,该事件每100ms发生一次.那么看一下handleChanges函数的定义吧,
handleChanges( Number: loadPercent, Number: playedPercentRelative,Number: playedPercentAbsolute, Number: playedTime, Number: totalTime )
参数:
1. loadPercent: 0-100,定义下载的百分比, 2. playedPercentRelative: 0-100,定义与当前下载的百分比相较的播放百分比.
3. playedPercentAbsolute: 0-100,定义当前播放的百分比, 4. playedTime: 当前播放时间,毫秒单位.
5. totalTime: 定义整个播放时间,,毫秒单位.
例子:
$("#jpId").jPlayer("onProgressChange", function(lp,ppr,ppa,pt,tt) {
$("#myLoadInfo").text(lp+"%"); // 显示下载的百分比.
$"#myPlayInfo").text(ppa+"%"); // 显示播放的百分比.
});
l. $(id).jPlayer( "getData", String: dataName ) : Variable
该方法是有来访问jPlay内部的配置信息.内部的配置对象也可以通过$(id).data("jPlayer.config")来访问,但是,however,这会开放所有的针对data的读/写操作,这个只对高级的开发者建议使用哦.参数:dataName,用来定义从jPlay插件内部配置对象中返回的data的元素名,返回的数据类型根据dataName不同而不同,什么都有的.下面是一大堆数据集,包括,构造器数据集(Constructor option data set at creation),内部配置数据集(Internal Configuration Data), 诊断信息(Diagnostic Information), cssID数据集(CSS Id Information), 分享cssId结构的对象集(Objects that share the cssId structure)
例子:
$("#jpId").jPlayer( {
ready: function() {
this.element.jPlayer("setFile", "elvis.mp3").jPlayer("play");
$("#jpHTML5").text("html5 = " + this.element.jPlayer("getData", "html5")); //显示html5相关的信息
}
});
setInterval( function() {//设置计时器
if($("#jpId").jPlayer("getData", "diag.isPlaying"))//判断是不是在播放
$("#jpPlaying").text("Listen up!"); //如果在放就说'听着'
} else {
$("#jpPlaying").text("Silence is golden!");//不是就说,沉默是金呐
}
var config = $("#jpId").data("jPlayer.config");//整个取出来
var mSecLeft = config.diag.totalTime - config.diag.playedTime;//还有多少时间才结束
$("#jpTimeLeft").text(mSecLeft + " milliseconds remain!");
}, 500 );
4\ jPlayer函数
a. $.jPlayer.convertTime( Number: milliSeconds ) : String
这个函数用来把时间从毫秒转换成小时/分/秒的字符串形式.字符串形式由$.jPlayer.timeFormat对象来定义.参数就是毫秒数.
例子:
$("#jpId").jPlayer("onProgressChange", function(lp,ppr,ppa,pt,tt) {
$"#playTime").text($.jPlayer.convertTime(pt)); //当前播放时间 默认格式'mm:ss'
$"#totalTime").text($.jPlayer.convertTime(tt)); //总共播放时间 默认格式'mm:ss'
});
5\ jPlayer对象
a. $.jPlayer.defaults : Object
这个对象保存有jPlayer实例的默认值,通过在jPlayer构造器中设置选项值,开发者可以修改$.jPlayer.defaults对象来配置所有后继的jPlayer实例,但是如果在实例化jPlayer之后,再改变默认值的话,那么对于已有的jPlayer实例就不会造成影响了.
b. $.jPlayer.timeFormat : Object
这个对象用来给出$.jPlayer.convertTime( Number: milliSeconds )函数返回的时间格式.有一系列的参数:
1.showHour: 布尔值,默认为false,显示小时, 2. showMin: 布尔值,默认为true,显示分钟, 3. showSec: 布尔值,默认为true,显示秒,
4.padHour: 布尔值,默认为false, 在小时数小10之前加0, 5. padMin, 6. padSec, 这两个参数这个作者完全进入了迷糊的场景了,不说也罢
7. sepHour, sepMin,sepSec, 跟在小时,分钟,秒之后的分隔符, 显然作者到这时还没有睡醒过来.
6\jPlayer预定义的CSS ids
a. 如前所说,jPlayer预定义了一套CSS id用与其方法相关联.这里作者交待了具体有哪些,还好这时醒过来了.具体有:
"play" : "jplayer_play"
"pause" : "jplayer_pause"
"stop" : "jplayer_stop"
"loadBar" : "jplayer_load_bar"
"playBar" : "jplayer_play_bar"
"volumeMin" : "jplayer_volume_min"
"volumeMax" : "jplayer_volume_max"
"volumeBar" : "jplayer_volume_bar"
"volumeBarValue" : "jplayer_volume_bar_value"
7\jPlayer皮肤
a. 为了实现标准化的皮肤开发途径,作者很得意的宣称他们使用了标准的HTML结构与CSS类命令传统.当然其中用到的id号必须要与上面说的一致,而且不能移作他用.皮肤的css应该使用下面的标准类名来定义. 皮肤应该能适用于HTML结构,单个及播放列表变量,因此皮肤需要一个单一的css文件,所有的艺术性工作都应该包含在一个图形文件中.警告,当前的皮肤结构不能支持访问性功能,如tabindex,accesskey等,这个结构有待进一步修订来解决这样的问题.
b. 标准的皮肤结构: 单一音轨
<div class="jp-single-player">
<div class="jp-interface">
<ul class="jp-controls">
<li id="jplayer_play" class="jp-play">play</li>
<li id="jplayer_pause" class="jp-pause">pause</li>
<li id="jplayer_stop" class="jp-stop">stop</li>
<li id="jplayer_volume_min" class="jp-volume-min">min volume</li>
<li id="jplayer_volume_max" class="jp-volume-max">max volume</li>
</ul>
<div class="jp-progress">
<div id="jplayer_load_bar" class="jp-load-bar">
<div id="jplayer_play_bar" class="jp-play-bar"></div>
</div>
</div>
<div id="jplayer_volume_bar" class="jp-volume-bar">
<div id="jplayer_volume_bar_value" class="jp-volume-bar-value"></div>
</div>
<div id="jplayer_play_time" class="jp-play-time"></div>
<div id="jplayer_total_time" class="jp-total-time"></div>
</div>
<div id="jplayer_playlist" class="jp-playlist">
<ul>
<li>Track title.</li>
</ul>
</div>
</div>
c. 标准的皮肤结构: 针对播放列表
<div class="jp-playlist-player">
<div class="jp-interface">
<ul class="jp-controls">
<li id="jplayer_play" class="jp-play">play</li>
<li id="jplayer_pause" class="jp-pause">pause</li>
<li id="jplayer_stop" class="jp-stop">stop</li>
<li id="jplayer_volume_min" class="jp-volume-min">min volume</li>
<li id="jplayer_volume_max" class="jp-volume-max">max volume</li>
<li id="jplayer_previous" class="jp-previous">previous</li>
<li id="jplayer_next" class="jp-next">next</li>
</ul>
<div class="jp-progress">
<div id="jplayer_load_bar" class="jp-load-bar">
<div id="jplayer_play_bar" class="jp-play-bar"></div>
</div>
</div>
<div id="jplayer_volume_bar" class="jp-volume-bar">
<div id="jplayer_volume_bar_value" class="jp-volume-bar-value"></div>
</div>
<div id="jplayer_play_time" class="jp-play-time"></div>
<div id="jplayer_total_time" class="jp-total-time"></div>
</div>
<div id="jplayer_playlist" class="jp-playlist">
<ul>
<!-- The function displayPlayList() uses this unordered list -->
</ul>
</div>
</div>
d. 皮肤的示例: 蓝色星期一(Blue Monday).
8. jPlay的兼容性
总之是兼容性很好的啦,基本上浏览器兼容性这块不用考虑的.