Plupload官网:点击打开链接 建议下载最新版本号,低版本号会出现浏览器兼容问题。
近期公司有个项目须要在web端使用多文件上传功能。刚開始准备使用HTML5来做。但是IE9下面是都不支持的,于是想到了flash,在网上搜了下各种开源的组件,最后决定使用Plupload。下面来介绍一下该组件使用时遇到的一些问题以及解决方式。
先贴出配置參数:
<script type="text/javascript">
// Initialize the widget when the DOM is ready
$(function() {
// Setup html5 version
$("#uploader").pluploadQueue({
// General settings
// General settings
runtimes : 'html5,flash,silverlight,html4',
url : 'stroage/upload',
unique_names:false,
// Maximum file size
max_file_size : '100mb',
chunk_size: '50mb',
multiple_queues :true,
// Resize images on clientside if we can
resize : {
width : 200,
height : 200,
quality : 90,
crop: true // crop to exact dimensions
},
// Specify what files to browse for
filters : [
{ title : "*", extensions : "*" }
],
// Rename files by clicking on their titles
rename: false,
// Enable ability to drag'n'drop files onto the widget (currently only HTML5 supports that)
dragdrop: false,
// Views to activate
views: {
list: true,
thumbs: true, // Show thumbs
active: 'thumbs'
},
// Flash settings
flash_swf_url : 'plupload/js/Moxie.swf',
// Silverlight settings
silverlight_xap_url : 'plupload/js/Moxie.xap'
});
});
</script>
效果图:
使用2.13版本号。上传一个大于1M的文件时候。Plupload自己主动将我文件名称改成了 blob,官方论坛上也有非常多人贴出了这个问题,也有不少的解决方式。
1、改动源代码
2、不正确文件进行分块,将chunk_size设置为0
3、将chunk_size的值设大
我使用前两种方式都未解决这个问题。最后将chunk_size设置为50mb,完美解决这个问题,详细原因不得而知。
使用过程中,想给文件加入上传速率。须要改动源代码,不废话。直接上代码
target.prepend(
'<div class="plupload_wrapper plupload_scroll">' +
'<div id="' + id + '_container" class="plupload_container">' +
'<div class="plupload">'+
'<div class="plupload_content">' +
'<div class="plupload_filelist_header">' +
'<div class="plupload_file_name">' + _('Filename') + '</div>' +
'<div class="plupload_file_action"> </div>' +
'<div class="plupload_file_status"><span>' + _('Status') + '</span></div>' +
'<div class="plupload_file_size">' + _('Size') + '</div>' +
'<div class="plupload_clearer"> </div>' +
'</div>' +
'<ul id="' + id + '_filelist" class="plupload_filelist"></ul>' +
'<div class="plupload_filelist_footer">' +
'<div class="plupload_file_name">' +
'<div class="plupload_buttons">' +
'<a href="#" class="plupload_button plupload_add" id="' + id + '_browse">' + _('Add Files') + '</a>' +
'<a href="#" class="plupload_button plupload_start">' + _('Start Upload') + '</a>' +
'</div>' +
'<span class="plupload_upload_status"></span>' +
'</div>' +
'<div class="plupload_file_action"></div>' +
'<span style="margin-left: 120px;" class="plupload_total_bytespersec">0kb/sec</span> '+
'<div class="plupload_file_status"><span class="plupload_total_status">0%</span></div>' +
'<div class="plupload_file_size"><span class="plupload_total_file_size">0 b</span></div>' +
'<div class="plupload_progress">' +
'<div class="plupload_progress_container">' +
'<div class="plupload_progress_bar"></div>' +
'</div>' +
'</div>' +
'<div class="plupload_clearer"> </div>' +
'</div>' +
'</div>' +
'</div>' +
'</div>' +
'<input type="hidden" id="' + id + '_count" name="' + id + '_count" value="0" />' +
'</div>'
);
function updateTotalProgress() {
$('span.plupload_total_bytespersec', target).html(parseInt(uploader.total.bytesPerSec/1024)+" kb/sec");
$('span.plupload_total_status', target).html(uploader.total.percent + '%');
$('div.plupload_progress_bar', target).css('width', uploader.total.percent + '%');
$('span.plupload_upload_status', target).html(
o.sprintf(_('Uploaded %d/%d files'), uploader.total.uploaded, uploader.files.length)
);
}
下面介绍下Plupload配置參数
实例化一个plupload对象时,也就是 new plupload.Uploader()
,须要传入一个对象作为配置參数。
后面内容中出现的plupload实例均是指new plupload.Uploader()
得到的实例对象
属性 | 类型 | 默认值 | 描写叙述 |
---|---|---|---|
browse_button | String / DOM | 触发文件选择对话框的DOM元素,当点击该元素后便后弹出文件选择对话框。该值能够是DOM元素对象本身。也能够是该DOM元素的id | |
url | String | server端接收和处理上传文件的脚本地址。能够是相对路径(相对于当前调用Plupload的文档),也能够是绝对路径 | |
filters | Object | { } | 能够使用该參数来限制上传文件的类型。大小等,该參数以对象的形式传入。它包含三个属性: mime_types:用来限定上传文件的类型,为一个数组。该数组的每个元素又是一个对象,该对象有title和extensions两个属性。title为该过滤器的名称,extensions为文件扩展名。有多个时用逗号隔开。该属性默觉得一个空数组,即不做限制。 max_file_size:用来限定上传文件的大小,假设文件体积超过了该值,则不能被选取。值能够为一个数字,单位为b,也能够是一个字符串,由数字和单位组成,如'200kb' prevent_duplicates:是否同意选取反复的文件,为true时表示不同意,为false时表示同意,默觉得false。假设两个文件的文件名称和大小都同样,则会被觉得是反复的文件 filters完整的配置示比例如以下(当然也能够仅仅配置当中的某一项): filters: { mime_types : [ //仅仅同意上传图片和zip文件 { title : "Image files", extensions : "jpg,gif,png" }, { title : "Zip files", extensions : "zip" } ], max_file_size : '400kb', //最大仅仅能上传400kb的文件 prevent_duplicates : true //不同意选取反复文件 } |
headers | Object | 设置上传时的自己定义头信息,以键/值对的形式传入,键代表头信息属性名,键代表属性值。 html4上传方式不支持设置该属性。 | |
multipart | Boolean | true | 为true 时将以multipart/form-data 的形式来上传文件,为false时则以二进制的格式来上传文件。html4上传方式不支持以二进制格式来上传文件。在flash上传方式中,二进制上传也有点问题。 而且二进制格式上传还须要在server端做特殊的处理。 一般我们用multipart/form-data的形式来上传文件就足够了。 |
multipart_params | Object | 上传时的附加參数,以键/值对的形式传入,server端但是使用$_POST来获取这些參数(以php为例)。比方:multipart_params: { one: '1', two: '2', three: { //值还能够是一个字面量对象 a: '4', b: '5' }, four: ['6', '7', '8'] //也能够是一个数组 } | |
max_retries | Number | 0 | 当发生plupload.HTTP_ERROR 错误时的重试次数,为0时表示不重试 |
chunk_size | Number/String | 0 | 分片上传文件时,每片文件被分割成的大小,为数字时单位为字节。也能够使用一个带单位的字符串。如"200kb" 。当该值为0时表示不使用分片上传功能 |
resize | Object | 能够使用该參数对将要上传的图片进行压缩,该參数是一个对象,里面包含5个属性: width:指定压缩后图片的宽度,假设没有设置该属性则默觉得原始图片的宽度 height:指定压缩后图片的高度。假设没有设置该属性则默觉得原始图片的高度 crop:是否裁剪图片 quality:压缩后图片的质量,仅仅对jpg格式的图片有效。默觉得90。 preserve_headers:压缩后是否保留图片的元数据, resize參数的配置示比例如以下: resize: { width: 100, height: 100, crop: true, quality: 60, preserve_headers: false } | |
drop_element | DOM/String/Array | 指定了使用拖拽方式来选择上传文件时的拖拽区域。即能够把文件拖拽到这个区域的方式来选择文件。该參数的值能够为一个DOM元素的id,也但是DOM元素本身,还能够是一个包含多个DOM元素的数组。假设不设置该參数则拖拽上传功能不可用。 眼下仅仅有html5上传方式才支持拖拽上传。 | |
multi_selection | Boolean | true | 能否够在文件浏览对话框中选择多个文件,true为能够,false为不能够。 默认true,即能够选择多个文件。 须要注意的是,在某些不支持多选文件的环境中。默认值是false。比方在ios7的safari浏览器中,由于存在bug,造成不能多选文件。 当然,在html4上传方式中。也是无法多选文件的。 |
required_features | Mix | 能够使用该參数来设置你必须须要的一些功能特征,Plupload会依据你的设置来选择合适的上传方式。由于,不同的上传方式。支持的功能是不同的。比方拖拽上传仅仅有html5上传方式支持,图片压缩则仅仅有html5,flash,silverlight上传方式支持。 该參数的值是一个混合类型,能够是一个以逗号分隔的字符串。 | |
unique_names | Boolean | false | 当值为true时会为每个上传的文件生成一个唯一的文件名称,并作为额外的參数post到server端。參数明为name ,值为生成的文件名称。 |
runtimes | String | html5,flash, silverlight, html4 | 用来指定上传方式,指定多个上传方式请使用逗号隔开。 普通情况下,你不须要配置该參数。由于Plupload默认会依据你的其它的參数配置来选择最合适的上传方式。 假设没有特殊要求的话,Plupload会首先选择html5上传方式,假设浏览器不支持html5。则会使用flash或silverlight,假设前面两者也都不支持,则会使用最传统的html4上传方式。假设你想指定使用某个上传方式。或改变上传方式的优先顺序,则你能够配置该參数。 |
file_data_name | String | file | 指定文件上传时文件域的名称,默觉得file ,比如在php中你能够使用$_FILES['file'] 来获取上传的文件信息 |
container | DOM/String | 用来指定Plupload所创建的html结构的父容器。默觉得前面指定的browse_button 的父元素。该參数的值能够是一个元素的id,也能够是DOM元素本身。 | |
flash_swf_url | String | js/Moxie.swf | flash上传组件的url地址,假设是相对路径。则相对的是调用Plupload的html文档。 当使用flash上传方式会用到该參数。 |
silverlight_xap_url | String | js/Moxie.xap | silverlight上传组件的url地址。假设是相对路径,则相对的是调用Plupload的html文档。当使用silverlight上传方式会用到该參数。 |
二、各种事件说明
要了解plupload的执行状况,靠的就是在这些事件了
Init |
---|
当Plupload初始化完毕后触发 监听函数參数:(uploader)
|
PostInit |
当Init事件发生后触发 监听函数參数:(uploader)
|
OptionChanged |
当使用Plupload实例的setOption()方法改变当前配置參数后触发 监听函数參数:(uploader,option_name,new_value,old_value)
|
Refresh |
当调用plupload实例的refresh()方法后会触发该事件,临时不清楚还有什么其它动作会触发该事件,但据我測试,把文件加入到上传队列后也会触发该事件。 监听函数參数:(uploader)
|
StateChanged |
当上传队列的状态发生改变时触发 监听函数參数:(uploader)
|
UploadFile |
当上传队列中某一个文件開始上传后触发 监听函数參数:(uploader,file)
|
BeforeUpload |
当队列中的某一个文件正要開始上传前触发 监听函数參数:(uploader,file)
|
QueueChanged |
当上传队列发生变化后触发,即上传队列新增了文件或移除了文件。QueueChanged事件会比FilesAdded或FilesRemoved事件先触发 监听函数參数:(uploader)
|
UploadProgress |
会在文件上传过程中不断触发,能够用此事件来显示上传进度 监听函数參数:(uploader,file)
|
FilesRemoved |
当文件从上传队列移除后触发 监听函数參数:(uploader,files)
|
FileFiltered |
暂不清楚该事件的意义,但依据測试得出,该事件会在每个文件被加入到上传队列前触发 监听函数參数:(uploader,file)
|
FilesAdded |
当文件加入到上传队列后触发 监听函数參数:(uploader,files)
|
FileUploaded |
当队列中的某一个文件上传完毕后触发 监听函数參数:(uploader,file,responseObject)
response:server返回的文本 responseHeaders:server返回的头信息 status:server返回的http状态码,比方200 |
ChunkUploaded |
当使用文件小片上传功能时,每个小片上传完毕后触发 监听函数參数:(uploader,file,responseObject)
offset:该文件小片在总体文件里的偏移量 response:server返回的文本 responseHeaders:server返回的头信息 status:server返回的http状态码,比方200 total:该文件(指的是被分割成了很多文件小片的那个文件)的总大小,单位为字节 |
UploadComplete |
当上传队列中全部文件都上传完毕后触发 监听函数參数:(uploader,files)
|
Error |
当错误发生时触发 监听函数參数:(uploader,errObject)
code:错误代码。详细请參考plupload上定义的表示错误代码的常量属性 file:与该错误相关的文件对象 message:错误信息 |
Destroy |
当调用destroy方法时触发 监听函数參数:(uploader)
|
三、Plupload实例的属性
属性 | 描写叙述 |
---|---|
id | Plupload实例的唯一标识id |
state | 当前的上传状态,可能的值为plupload.STARTED 或plupload.STOPPED ,该值由Plupload实例的stop() 或statr() 方法控制。默觉得plupload.STOPPED |
runtime | 当前使用的上传方式 |
files | 当前的上传队列,是一个由上传队列中的文件对象组成的数组 |
settings | 当前的配置參数对象 |
total | 表示总体进度信息的QueueProgress对象 |
四、Plupload实例的方法
方法 | 描写叙述 |
---|---|
init() | 初始化Plupload实例 |
setOption(option, [value]) | 设置某个特定的配置參数,option为參数名称,value为要设置的參数值。 option也能够为一个由參数名和參数值键/值对组成的对象,这样就能够一次设定多个參数。此时该方法的第二个參数value会被忽略。 |
getOption([option]) | 获取当前的配置參数,參数option为须要获取的配置參数名称,假设没有指定option,则会获取全部的配置參数 |
refresh() | 刷新当前的plupload实例,临时还不明确什么时候须要使用 |
start() | 開始上传队列中的文件 |
stop() | 停止队列中的文件上传 |
disableBrowse(disable) | 禁用或启用plupload的文件浏览按钮,參数disable 为true 时为禁用,为false 时为启用。默觉得true |
getFile(id) | 通过id来获取文件对象 |
addFile(file, [fileName]) | 向上传队列中加入文件,假设成功加入了文件。会触发FilesAdded 事件。參数file为要加入的文件,能够是一个原生的文件,或者一个plupload文件对象,或者一个 |
removeFile(file) | 从上传队列中移除文件,參数file 为plupload文件对象或先前指定的文件名称称 |
splice(start, length) | 从上传队列中移除一部分文件。start 为開始移除文件在队列中的索引,length 为要移除的文件的数量,该方法的返回值为被移除的文件。该方法会触发 |
trigger(name, Multiple) | 触发某个事件。
|
hasEventListener(name) | 用来推断某个事件是否有监听函数,name 为事件名称 |
bind(name, func, scope) | 给某个事件绑定监听函数,name 为事件名,func 为监听函数。scope 为监听函数的作用域,也就是监听函数中this的指向 |
unbind(name, func) | 移除事件的监听函数,name 为事件名称,func 为要移除的监听函数 |
unbindAll() | 移除全部事件的全部监听函数 |
destroy() | 销毁plupload实例 |
五、文件对象的属性和方法
在非常多事件监听函数中。都会提供文件对象给你
属性/方法 | 描写叙述 |
---|---|
id | 文件id |
name | 文件名称。比如"myfile.gif" |
type | 文件类型。比如"image/jpeg" |
size | 文件大小,单位为字节,当启用了客户端压缩功能后。该值可能会改变 |
origSize | 文件的原始大小。单位为字节 |
loaded | 文件已上传部分的大小,单位为字节 |
percent | 文件已上传部分所占的百分比。如50就代表已上传了50% |
status | 文件的状态,可能为下面几个值之中的一个:plupload.QUEUED , plupload.UPLOADING , plupload.FAILED , plupload.DONE |
lastModifiedDate | 文件最后改动的时间 |
getNative() | 获取原生的文件对象 |
getSource() | 获取mOxie.File 对象。想了解mOxie是什么东西,能够看下https://github.com/moxiecode/moxie/wiki/API |
destroy() | 销毁文件对象 |
六、QueueProgress 对象的属性
plupload实例的total属性是一个QueueProgress对象
属性 | 描写叙述 |
---|---|
size | 上传队列中全部文件加起来的总大小,单位为字节 |
loaded | 队列中当前已上传文件加起来的总大小,单位为字节 |
uploaded | 已完毕上传的文件的数量 |
failed | 上传失败的文件数量 |
queued | 队列中剩下的(也就是除开已经完毕上传的文件)须要上传的文件数量 |
percent | 整个队列的已上传百分比。如50就代表50% |
bytesPerSec | 上传速率,单位为 byte/s,也就是 字节/秒 |
七、plupload命名空间上的一些属性
plupload的命名空间上有一些属性,用来表示一些常量。记住,不是plupload实例的属性,而是plupload的属性
属性名称 | 描写叙述 |
---|---|
VERSION | 当前plupload的版本号号 |
STOPPED | 值为1。代表上传队列还未開始上传或者上传队列中的文件已经上传完毕时plupload实例的state 属性值 |
STARTED | 值为2。代表队列中的文件正在上传时plupload实例的state 属性值 |
QUEUED | 值为1。代表某个文件已经被加入进队列等待上传时该文件对象的status 属性值 |
UPLOADING | 值为2。代表某个文件正在上传时该文件对象的status 属性值 |
FAILED | 值为4,代表某个文件上传失败后该文件对象的status 属性值 |
DONE | 值为5,代表某个文件上传成功后该文件对象的status 属性值 |
GENERIC_ERROR | 值为-100,发生通用错误时的错误代码 |
HTTP_ERROR | 值为-200,发生http网络错误时的错误代码,比如服务气端返回的状态码不是200 |
IO_ERROR | 值为-300,发生磁盘读写错误时的错误代码,比如本地上某个文件不可读 |
SECURITY_ERROR | 值为-400,发生由于安全问题而产生的错误时的错误代码 |
INIT_ERROR | 值为-500,初始化时错误发生的错误代码 |
FILE_SIZE_ERROR | 值为-600。当选择的文件太大时的错误代码 |
FILE_EXTENSION_ERROR | 值为-601,当选择的文件类型不符合要求时的错误代码 |
FILE_DUPLICATE_ERROR | 值为-602。当选取了反复的文件而配置中又不同意有反复文件时的错误代码 |
IMAGE_FORMAT_ERROR | 值为-700,发生图片格式错误时的错误代码 |
IMAGE_MEMORY_ERROR | 当发生内存错误时的错误代码 |
IMAGE_DIMENSIONS_ERROR | 值为-702。当文件大小超过了plupload所能处理的最大值时的错误代码 |