API 指南


初始化


针对目标 HTML 元素,调用其 jQuery 对象的 .fileupload() 方法,便可完成 FileUpload 插件的初始化:

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

目标元素通常是保存文件上传表单的容器元素,或文件上传表单本身。当然它也可以是一个自定义 UI 的文件 input 元素,或者是一个作为配置项参数的 url。

初始化方法的第一个参数是一个 Options 对象,其各项值决定了对插件进行初始化时所对应的各项配置行为:

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

另外,也可以将配置项以 HTML5 data 属性的方式传递给初始化方法:

/* 本例等同于使用以下配置项来初始化 FileUpload 插件
{
    url: '/path/to/upload/handler.json',
    sequentialUploads: true,
    formData: {script: true}
}
*/
<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();

配置项更改


插件在初始化完成之后也是可以更改配置项的:

$('#fileupload').fileupload(
    'option',
    'url',
    '/path/to/upload/handler.json'
);

如果调用时没有设置第三个参数(即配置值),那么这种情况下 option 方法表示获取该配置项的当前值:

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

调用方法时第二个参数可以传递一个对象,便可实现一次修改多个配置项

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

注销


要从元素节点中删除 FileUpload 插件功能,请调用 destroy 方法:

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

所有已注册的事件监听器也将一并删除。

禁用 / 启用


和其他基于 jQueryUI 插件库 的插件一样,FileUpload 插件也拥有 disabled/enabled 功能:

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

上传进度


通过 progress 方法获取整体进度数据:

var overallProgress = $('#fileupload').fileupload('progress');

上传文件数


通过 active 方法获取正在上传的文件数量:

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

程序化上传


通常情况下,待上传文件都是通过文件输入按钮或将其拉入特定的拖放区域来实行上传。

然而,对于支持 XHR 的浏览器而言,也可以以编程方式触发上传行为(请参阅浏览器支持细则):

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

add 接口的第二个参数必须是一个包含有 files 属性的对象,其属性值则要求以 FileBlob 对象作为元素的数组(或者类数组列表)。

对主流浏览器而言,可以通过读取文件输入框的 files 字段属性来获取 filesList,例:

var filesList = $('input[type="file"]').prop('files');

若还存在其他属性,表示其覆盖 upload 实例的对应配置项,例如 url:

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

add 方法通过将文件添加到上传队列来上传文件,这和通过文件输入框或者拖拽上传的方式是相同的。

另外也可以使用 send 方法直接发送文件:

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

send 方法会返回一个 jqXHR 对象,其主要功能是允许我们把 ajax 文件上传请求的回调函数绑定到上面:

var jqXHR = $('#fileupload').fileupload('send', {files: filesList})
    .success(function (result, textStatus, jqXHR) {/* ... */})
    .error(function (jqXHR, textStatus, errorThrown) {/* ... */})
    .complete(function (result, textStatus, jqXHR) {/* ... */});
注意:send 方法会直接发送给定的文件,而不是将它们拆分成多次请求。所以即便你的 files 参数包含了 3 个文件,它也只会对服务端发送一次请求。而如果 multipart 配置项为 true,它仍然会将 3 个文件视为 multipart 请求的内容发送一次,否则它将只发送第一个文件。
因此,当你需要应用多重请求来发送多个文件时,要么多次调用 send 方法进行多次发送,要么改用 add 方法。
程序化上传中关于不支持 XHR 文件上传的浏览器的解决方案

对于不支持 XHR 文件上传的浏览器,也可以利用 fileInput 配置项来实现 addsend 方法的调用:

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

上面 fileInput 属性必须是一个 jQuery 实例,其应指向一个有效文件选择的 file 类型的 input 元素。

XHR 文件上传需要使用到 Iframe 传输脚本 译者注:该脚本为插件内置脚本,位于 js/jquery.iframe-transport.js

回调函数


FileUpload 插件提供了几种注册回调函数的方式。

其中一种方式就是将回调函数作为配置项参数中的一个属性:

$('#fileupload').fileupload({
    drop: function (e, data) {
        $.each(data.files, function (index, file) {
            alert('Dropped file: ' + file.name);
        });
    },
    change: function (e, data) {
        $.each(data.files, function (index, file) {
            alert('Selected file: ' + file.name);
        });
    }
});

第二种方式是将回调方法绑定到插件元素的事件监听器上:

$('#fileupload')
    .bind('fileuploaddrop', function (e, data) {/* ... */})
    .bind('fileuploadchange', function (e, data) {/* ... */});

每一个事件名称都会以 fileupload 作为前缀。

注意:通过 bind 方法绑定事件监听器的方式是 jQuery FileUpload 插件 UI 版本(jquery.fileupload-ui.js)注册回调函数的首选方式。

其中有一个特殊的回调函数叫 add 回调,该函数的 data 参数中提供了一个 submit 函数,其功能是提交文件开始上传:

$('#fileupload').fileupload({
    add: function (e, data) {
        data.submit();
    }
});

add 回调函数的 data.submit() 函数会返回一个 jqXHR 对象,可以把 ajax 请求的回调函数绑定到该对象上:

$('#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) {/* ... */});
    }
});

中途取消


上传过程可以通过调用 jqXHR 对象的 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();
    }
});

提交文件前检索额外参数


请参阅实现文件异步提交的相关指南。