胡新敏的个人博客

本片文章是接着上一篇文章继续写的jQuery-file-upload使用方法详解（一）

API详解

初始化

$('#fileupload').fileupload([options]);

初始化的HTML对象，可以是一个包含文件上传表单的容器，也可以是上传表单本身，还可以是一个file input对象。

数据属性

配置项不仅可以在初始化的时候通过options传入，还可以通过给初始化的HTML对象设置HTML5的数据属性进行设置：

<input id="fileupload" type="file" name="files[]" multiple
    data-url="/path/to/upload/handler.json"
    data-sequential-uploads="true"
    data-form-data='{"script": "true"}'>

更改配置项

你可以在初始化之后随时进行更改配置项：

$('#fileupload').fileupload(
    'option',
    'url',
    '/path/to/upload/handler.json'
);
$('#fileupload').fileupload(
    'option',
    {
        url: '/path/to/upload/handler.json',
        sequentialUploads: true
    }
);

如果你没有要设置的值，会把它当做一个getter一样取出当前的值：

var dropZone = $('#fileupload').fileupload(
    'option',
    'dropZone'
);

销毁

你可以通过调用destory方法在元素对象上移除该组件方法：

$('#fileupload').fileupload('destroy');

启用/禁用

你可以通过调用disabled/enabled来启用或者禁用：

$('#fileupload').fileupload('disable');
$('#fileupload').fileupload('enable');

获得上传进度

$('#fileupload').fileupload('progress');

获得正在上传的任务数量

var activeUploads = $('#fileupload').fileupload('active');

程序化文件上传

通常我们都是使用input元素或者直接拖拽文件来添加文件，如果浏览器支持XHR文件上传的话，我们还可以使用程序化的方式自动添加文件：

$('#fileupload').fileupload('add', {files: filesList});

注意第二个参数，一定要是一个类数组对象。你还可以改写配置项：

$('#fileupload').fileupload('add', {files: filesList, url: '/path/to/upload/handler.json'});

你还可以直接使用send方法直接发送文件：

$('#fileupload').fileupload('send', {files: filesList});

send方法会返回一个jQuery的XHR对象，你可以添加一些回调函数：

var jqXHR = $('#fileupload').fileupload('send', {files: filesList})
    .success(function (result, textStatus, jqXHR) {/* ... */})
    .error(function (jqXHR, textStatus, errorThrown) {/* ... */})
    .complete(function (result, textStatus, jqXHR) {/* ... */});

需要注意的是，send方法并不会把多个文件分成多个请求发送，如果你有多个文件，如果multipart选项为true的话，它会把所有的文件一次性上传，如果为false的话，它只会上传第一个文件。所以，如果你想要多次上传文件的话，要么多次调用send方法，要么使用add方法。

在浏览器不支持XHR文件上传时使用程序化文件上传

如果浏览器不支持XHR文件上传时，你可以使用fileInput选项来使用程序化文件上传：

$('#some-file-input-field').bind('change', function (e) {
    $('#fileupload').fileupload('add', {
        fileInput: $(this)
    });
});

这种方法实际上使用了iframe的方式进行上传文件。

回调函数

jQuery-file-upload提供了多个回调函数，有两种方式可以使用，一种是直接在options里面使用，一种是用函数监听的方式使用，不过要多加一个fileupload前缀名：

$('#fileupload').fileupload({
    drop: function (e, data) {
    },
    change: function (e, data) {
    }
});
$('#fileupload')
    .on('fileuploaddrop', function (e, data) {/* ... */})
    .on('fileuploadchange', function (e, data) {/* ... */});

jQuery-file-upload提供的回调函数一共有如下几种：

$('#fileupload')
    .on('fileuploadadd', function (e, data) {/* ... */})
    .on('fileuploadsubmit', function (e, data) {/* ... */})
    .on('fileuploadsend', function (e, data) {/* ... */})
    .on('fileuploaddone', function (e, data) {/* ... */})
    .on('fileuploadfail', function (e, data) {/* ... */})
    .on('fileuploadalways', function (e, data) {/* ... */})
    .on('fileuploadprogress', function (e, data) {/* ... */})
    .on('fileuploadprogressall', function (e, data) {/* ... */})
    .on('fileuploadstart', function (e) {/* ... */})
    .on('fileuploadstop', function (e) {/* ... */})
    .on('fileuploadchange', function (e, data) {/* ... */})
    .on('fileuploadpaste', function (e, data) {/* ... */})
    .on('fileuploaddrop', function (e, data) {/* ... */})
    .on('fileuploaddragover', function (e) {/* ... */})
    .on('fileuploadchunksend', function (e, data) {/* ... */})
    .on('fileuploadchunkdone', function (e, data) {/* ... */})
    .on('fileuploadchunkfail', function (e, data) {/* ... */})
    .on('fileuploadchunkalways', function (e, data) {/* ... */});

其中add回调函数最为特殊，因为它返回的data参数提供了一个submit方法，可以用来开始上传文件，这个方法返回一个jQuery的XHR对象：

$('#fileupload').fileupload({
    add: function (e, data) {
        data.submit();
}
$('#fileupload').fileupload({
    add: function (e, data) {
        var jqXHR = data.submit()
            .success(function (result, textStatus, jqXHR) {/* ... */})
            .error(function (jqXHR, textStatus, errorThrown) {/* ... */})
            .complete(function (result, textStatus, jqXHR) {/* ... */});
    }
});

取消上传

调用jQuery的XHR的abort方法即可取消上传：

var jqXHR = $('#fileupload').fileupload('send', {files: filesList})
    .error(function (jqXHR, textStatus, errorThrown) {
        if (errorThrown === 'abort') {
            alert('File Upload has been canceled');
        }
    });
$('button.cancel').click(function (e) {
    jqXHR.abort();
});

提供一个替代的文件名

上传文件File的name属性是只读的，但是你可以通过设置uploadName为每一个文件提供一个替代的文件名：

$('#fileupload').fileupload({
    add: function (e, data) {
        var count = data.files.length;
        var i;
        for (i = 0; i < count; i++) {
            data.files[i].uploadName =
                Math.floor(Math.random() * 1000) + '_' + data.files[i].name;
        }
        data.submit();
    }
});

通过Ajax获取额外的参数后再开始上传文件

如果你想在使用AJAX从后台获取数据之后，然后再开始上传文件的话，可以通过改写add或者submit的回调：

//这种方式会改变上传的默认UI界面
$('#fileupload').fileupload({
    add: function (e, data) {
        $.getJSON('/example/url', function (result) {
            data.formData = result; // e.g. {id: 123}
            data.submit();
        });
    } 
});
//这种方式不会改变默认的上传UI界面
$('#fileupload').fileupload({
    add: function (e, data) {
        var that = this;
        $.getJSON('/example/url', function (result) {
            data.formData = result; // e.g. {id: 123}
            $.blueimp.fileupload.prototype
                .options.add.call(that, e, data);
        });
    } 
});
//使用submit
$('#fileupload').fileupload({
    submit: function (e, data) {
        var $this = $(this);
        $.getJSON('/example/url', function (result) {
            data.formData = result; // e.g. {id: 123}
            data.jqXHR = $this.fileupload('send', data);
        });
        return false;
    } 
});

配置项详解

jQuery-file-upload组件由最基本的脚本jquery.fileupload.js提供基本的API以及附加的插件提供完整的用户界面jquery.fileupload-ui.js

AJAX配置选项

jQuery-file-upload组件使用的是jQuery的ajax方法，就算浏览器不支持XHR也没事，因为使用了iframe tranport插件。processData， contentType，cache都是默认设置为false的，不该更改，timeout默认设置为0。它还有下面这些参数需要设置：

url上传地址，如果没有设置，则使用表单action地址，如果也没有则使用当前页面地址。
type上传方式，默认为POST
dataType后台返回数据类型

通用配置选项

dropZone拖拽放置文件对象，默认为整个文档，设置为null或者空对象来禁用拖拽功能
pasteZone粘贴上传文件，默认为整个文档，目前只有chrome支持
fileInput是file类型的inputjQuery对象，如果没有定义则为初始化对象内部的file类型的input，可以设置为null或者空来禁用。
replaceFileInput默认为true，每当file类型的input触发change事件时，都会被它的克隆元素替代，这在iframe队列上传和再次上传同一个文件时是必需的。
paramName文件form data的参数名，如果没有设置的话，则使用file的input的name属性名，如果也没有的话，则为files[]
formAcceptCharset设置iframe上传时的accept-charset属性，若没有设置则使用表单的accept-charset属性值，示例utf-8
singleFileUploads默认true，将每个文件都使用一个独立的请求发送，如果想要使用一个请求发送多个文件的话，可以将之设置为false，并且multipart选项也要设置为true。
limitMultiFileUploads限制一个请求中发送多个文件的数量，默认为undefined，可设置为整数值。当singleFileUploads为true或者limitMultiFileUploadSize被设置时，该选项将被忽略。
limitMultiFileUploadSize限制一个请求上传文件的数量，使的文件大小不超过设定的值，默认为undefined，可以设置为整数值，当singleFileUploads为true时该选项将被忽略。
limitMultiFileUploadSizeOverhead同一个请求中上传多个文件时，含有太多的字节数，因此该选项可以为每个文件增添额外的开销，也就是使文件数*开销大小加所有文件大小小于limitMultiFileUploadSize，默认值为512
sequentialUploads队列上传，默认为false，也就是可以同时并行上传多个请求。
limitConcurrentUploads限制同时上传请求数，默认为undefined，可以设置为整数。
forceIframeTransport强制使用iframe上传，当后台无法设置Access-Control-Allow-Origin来满足XHR的跨域上传时，这个选项很有用，默认为false。
initialIframeSrc当时有iframe进行上传时重写iframe的src，默认为javascript:false;
redirect当时有iframe进行跨域上传时，服务端上传完成返回需要跳转的地址，然后把上传信息以URL-encoded形式写在URL参数里。
redirectParamName重定向地址参数名，如果空的话，则为redirect
postMessage使用postMessage上传方式时，设置使用postMessageAPI页面的地址。
multipart默认为true，发送请求都是multipart/form-data的方式，如果设置为false，将会以流的方式进行发送，并且无法发送额外的form-data数据。
maxChunkSize默认为undefined，将大文件进行分片上传，如果该选项设置为0，undefined，null，或者浏览器不支持BlobAPI的话，将会整个上传。当在Firefox小于7的版本使用时，multipart必须设置为false，因为Gecko 2.0添加Blobs时候发送multipart请求时是一个空的filename，但是一些后台（PHP ，Django）无法解析空filename的multipart请求。如果启用了改选项，且singleFileUploads为false时，只有选择的第一个文件将会被上传。
uploadedBytes默认为undefined，已经上传的字节数，当使用非multipart或者分片上传被终止时，可以通过设置该选项来恢复上传，最有用的地方就是在add或者send的回调函数里。
recalculateProgress重新计算上传进度，默认为true，默认的，上传失败或者终止会从总体进度计算中移除，你可以将之设置为false来防止重新计算进度。

ABOUT ME