配置项手册


jQuery FileUpload 插件由一个提供文件上传 API 的基础组件(jquery.fileupload.js)和一个提供完整用户界面的 UI 组件(jquery.fileupload-ui.js)所构成。

UI 组件拥有基础组件的所有配置项,其是在基础组件上新增了一些额外的配置项。

有关如何应用配置项的示例代码,请参阅 API 指南 文档。

AJAX 配置项


jQuery FileUpload 插件使用 jQuery.ajax() 来处理文件上传请求。即便对于不支持 XHR 的浏览器而言,在使用了 Iframe 传输组件之后也同样是使用 jQuery.ajax() 函数来提交请求。

jQuery FileUpload 插件的配置项会作为参数传递给 jQuery.ajax() 函数,ajax 配置(ajaxSettings)或回调函数都可以在插件的配置项中进行设置。

务必将 ajax 的 processDatacontentTypecache 选项设置为 false,否则可能导致文件无法正常上传。

另外 timeout 选项需要设为 0。有关这背后的原因,请参阅 留言板 #3399

接下来介绍插件的配置项,大部分在插件内已设默认值,但在你的程序需要的情况下都可以自由设置:

url

字符串,内容是需要发送请求的 URL 地址。

如果未定义或设为空字符串,那么发送的 URL 会从 fileupload 绑定的 form 元素的 action 属性中取值,若 action 也没有定义,那么会将请求发送到当前页面。

  • 类型:string
  • 默认值:location.href
  • 示例:'/path/to/upload/handler.json'
type

文件上传的 HTTP 请求方法。可以是“POST”、“PUT”或“PATCH”,默认为“POST”。

  • 类型:string
  • 默认值:'POST'
  • 示例:'PUT'
注意:由于应用 iframe 传输上传的标准 HTML 表单仅支持“POST”方法,所以只有支持 XHR 上传的浏览器能够使用“PUT”和“PATCH”方法。参阅浏览器支持细则
若在非 XHR 浏览器上设置了“PUT”或“PATCH”方法,那么 iframe 传输组件实际上会通过“POST”方法进行发送,并且 URL 参数中原始的 method 选项值会设为 "_method"。
注意:如上所述,使用“_method”作为请求方法是一种常见用法。举个例子,“Ruby on Rails”框架就是在每个表单中都埋一个 hidden 类型的 input 元素并将其 name 属性赋值为“_method”,这样在有必要的情况下它就可以覆盖掉你在本配置项设置的值。
dataType

期望从服务端返回的数据类型。

  • 类型:string
  • 默认值:'json'
  • 示例:'json'
注意:本插件的 UI 组件会将 "json" 设为本配置的默认值。

通用配置项


  • 类型:string
  • 示例:'myfileupload'
dropZone

默认情况下,我们以 html document 创建的 jQuery 对象作为拖放区域,即整个窗口都是拖放区域。

若设为 null 或指向一个空 jQuery 对象则表示禁用文件拖放功能:

  • 类型:jQuery Object
  • 默认值:$(document)
如果你希望仅允许在特定区域进行拖放功能,请添加以下 js 代码:
$(document).on('drop dragover', function (e) {
    e.preventDefault();
});

表示在 document 对象上禁用所有“drop”和“dragover”事件操作。

pasteZone

设置一个 jQuery 对象 作为粘贴区域,默认不启用粘贴功能。

若 jQuery 对象有设置,则启用粘贴功能:

  • 类型:jQuery Object
  • 默认值:undefined
  • 示例:$(document)
注意:目前只有 Google Chrome 浏览器支持通过“复制”&“粘贴”进行文件上传。
fileInput

该配置项会设置一个文件输入元素的 jQuery 对象,主要用于监听 change 事件。

如果配置项未定义,那么会将插件初始化时对应的 file input 对象作为配置值。

设为 null 或空对象表示禁用 change 监听功能。

  • 类型:jQuery Object
  • 示例:$('input:file')
replaceFileInput

默认情况下,在每次触发 change 事件之后,上文 fileinput 对应的 input 对象都会替换为一个元素副本(通过 .clone() 方法)。

这种机制对于 iframe 队列传输而言是必须的,并且可以保证同一 file input 对象中可以重复地有效触发 change 事件(更深入的原因请参阅常见问题解答)。如果我们把配置值设为 false 则禁用这种机制。

  • 类型:boolean
  • 默认值:true
paramName

表单数据的文件参数名称(请求参数名称)。译者注:即服务端中 Request 参数中对应上传文件的参数名

如果未定义或为空,则使用 file input 字段的 name 属性,如果其 name 属性也为空,则使用“files[]”。可以是一个字符串或字符串数组。

  • 类型:string 或 array
  • 示例:'attachments[]'
formAcceptCharset

允许为 iframe 上传表单设置 accept-charset 属性。

如果未设置 formAcceptCharset,则使用 form 标签的 accept-charset 属性(前提是定义了 accept-charset 属性)作为参数值。

  • 类型:string
  • 示例:'utf-8'
singleFileUploads

多文件上传时,默认情况下,选择的每个文件都是通过 XHR 数据类型单独请求上传的。

将配置项设为 false 则可以合并为一个请求来上传文件。

注意:将多文件合并为单个请求的前提是要求 multipart 配置项设为 true(默认)。
  • 类型:boolean
  • 默认值:true
limitMultiFileUploads

多文件上传合并为单次 XHR 请求的时候,将本项设为一个大于 0 的整数用来限制上传的文件数量:

  • 类型:integer
  • 默认值:undefined
  • 示例:3
注意:如果 singleFileUploads 设为 true 或者 limitMultiFileUploadSize 设置了大小并且浏览器支持提示文件大小,那么本项会被直接忽略。
limitMultiFileUploadSize

多文件上传合并为单次 XHR 请求的时候,本配置项用来设置传输文件总大小的字节限制:

  • 类型:integer
  • 默认值:undefined
  • 示例:1000000
注意:singleFileUploads 为 true 的时候,本项直接忽略。
limitMultiFileUploadSizeOverhead

在多文件上传时每个上传的文件都会有几个字节的请求头,所以当多文件上传合并为单个请求的时候,需要为每个文件在实际大小的基础上加上本配置值的长度,然后再去判断是否超过 limitMultiFileUploadSize 的大小限制:

  • 类型:integer
  • 默认值:512
sequentialUploads

设为 true 表示对所有文件按顺序提交上传请求,而不是同时发出请求。

  • 类型:boolean
  • 默认值:false
limitConcurrentUploads

用于限制并发上传的文件数量,需要设置为大于 0 的整数值。

  • 类型:integer
  • 默认值:undefined
  • 示例:3
注意:如果 sequentialUploads 设为 true,本项会被直接忽略。
forceIframeTransport

若设为 true 将强制以 iframe 传输方式上传文件,即便在支持 XHR 的浏览器下。

如果无法为跨域上传所需的服务端处理程序设置 Access-Control-Allow-Origin 请求头,那这项配置就会很有用。

  • 类型:boolean
  • 默认值:false
initialIframeSrc

本配置项仅供 iframe 传输组件使用,并允许覆盖初始 iframe src 的 URL。

  • 类型:string
  • 默认值:'javascript:false;'
redirect

在跨域 iframe 传输上传的时候,为源服务端(即用来跑文件上传表单的那台 web 服务端)配置一个重定向 URL 地址。如果有设置,那么该值将作为表单数据的一部分发送给目标服务端。

目标服务器应该在上传完成后将上传信息经过 JSON 编码后附加到 URL 字符串后面,然后再让浏览器重定向到这个 URL,例如,可以在设置 redirect 时给 URL 后面附加一个“%s”字符串,末了通过将“%s”替换为需要反馈的 JSON 字符串。

  • 类型:string
  • 示例:'http://example.org/cors/result.html?%s'
redirectParamName

重定向 URL 的参数名称,作为表单数据的一部分发送。如果留空,则设置为‘redirect’。

  • 类型:string
  • 示例:'redirect-url'
postMessage

postMessage 传输组件也是一套可以实现跨域传输的工具,可以通过在源服务器架设一个 postMessage API 并将本配置项指向这个接口的地址来启用 postMessage。

  • 类型:string
  • 示例:'http://example.org/upload/postmessage.html'
注意:目前只有 Google Chrome 浏览器可完美支持本功能。
multipart

默认情况下,XHR 文件会作为 multipart/form-data 编码方式发送。

Iframe 传输始终使用 multipart/form-data 编码方式。

如果本配置项设为 false,那么文件内容会作为流文件传输给服务端,而不是发送用于 XMLHttpRequest 文件上传的 RFC 2388 多部分消息译者注:即以 multipart/form-data 方式编码的数据

非分段上传也称为 HTTP PUT 文件上传

注意:multipart 设置为 false 时,将忽略其他表单数据。
Safari 5.1 不支持文件流方式(multipart: false)上传 - 参阅 issue #700
  • 类型:boolean
  • 默认值:true
maxChunkSize

当大文件需要拆分成多块上传时,本配置设置的是单块的大小上限。如果设为 0、null、未定义或浏览器不支持所依赖的 Blob 接口,那么文件都将作为一个整体上传。

若需要在 Mozilla Firefox <7 中进行分块上传,那 multipart 配置项必须设为 false。这是因为 Gecko 2.0(FireFox 4 等)在使用 FormData 接口构建分段上传请求时添加了一个文件名为空的 Blob 对象 - 参阅 Bugzilla #649150 (已修复于 FF 7.0)。而有一些服务端框架(包括 PHP 和 Django)面对所上传的数据是无法处理空文件名的。

注意:如果设置了本配置,而 singleFileUploads 又设为 false 的话,那么只有首个文件分块后的第一块能够成功上传。
  • 类型:integer
  • 默认值:undefined
  • 示例:10000000
uploadedBytes

本配置项设置的是已上传的字节数,也就是说当上传开始时会越过已上传的文件部分,从所设置的大小之后开始传输。

当一个非分段上传(multipart: false - 文件流方式)或分块多段上传被中止后,可以用本项设置已上传的字节数来恢复上传。本配置项最常用的地方是在“add”或“send”回调函数中去修改 Options 对象,因为每次请求文件上传时都要克隆一次 Options 对象。

  • 类型:integer
  • 默认值:undefined
  • 示例:10000000
recalculateProgress

默认情况下,文件上传的整体进度会剔除已失败、中止或错误的文件部分再进行计算。

设置本项为 false 则表示全局整体进度不会排除上述发生错误部分的文件进度。

  • 类型:boolean
  • 默认值:true
progressInterval

触发进度数据采集事件的最小时间间隔,单位毫秒。译者注:即间隔多久采集一次进度条数据。

  • 类型:integer
  • 默认值:100
bitrateInterval

计算进度比特率数据的最小时间间隔,单位毫秒。

  • 类型:integer
  • 默认值:500
autoUpload

默认情况下,已添加的文件会在用户点击开始按钮后才开始上传。将本项设为 true 表示启用自动上传。

  • 类型:boolean
  • 默认值:true

基础组件中本配置项默认为 true

formData

需要发送给服务端的其他附加数据可以使用本配置项一同提交,它可以是一个由对象(有且仅有 name 和 value 两属性)组成的数组、一个返回值是上述数组的函数、一个 FormData 对象(用于 XHR 文件上传)或者仅仅只是一个简单对象。

表单的第一个 fileinput 也会作为函数参数给出。

注意:multipart 设为 false 时,将忽略其他表单数据。
  • 类型:Array、Object、function 或 FormData
  • 默认值:将表单字段作为序列化数组返回的函数:
    function (form) {
        return form.serializeArray();
    }
  • 示例:
    [
        {
            name: 'a',
            value: 1
        },
        {
            name: 'b',
            value: 2
        }
    ]

回调函数


所有回调既可以是函数类型,也可以绑定为事件监听器,使用事件监听方式时需要在回调名称加上“fileupload”作为前缀:

$('#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('fileuploadchunkbeforesend', function (e, data) {/* ... */})
    .on('fileuploadchunksend', function (e, data) {/* ... */})
    .on('fileuploadchunkdone', function (e, data) {/* ... */})
    .on('fileuploadchunkfail', function (e, data) {/* ... */})
    .on('fileuploadchunkalways', function (e, data) {/* ... */});
注意:若使用了本插件的 UI 组件,那么通过 bind 方法(或可以在 jQuery 1.7+ 中使用 on 方法)绑定事件监听器会是你注册回调函数的首选方式。
add

Add 回调可以视为文件上传请求队列回调。无论是通过文件输入框选择、拖放还是 add 接口调用,一旦文件被添加便会调用本回调函数。

Data 参数可以覆盖插件的配置项,也可以定义 ajax 设置。

data.files 保存上传请求的文件列表:如果 singleFileUploads 配置项设为 true(默认),那么被选择的文件每提交一次 XHR 上传就会调用一次 add 回调,也就是说这种情况下回调的 data.files 数组长度会固定为 1,正如每个文件都是独立上传。否则,对于单次选择(即便多个文件)只会调用一次 add 回调。

当调用 data 参数中的 submit 方法时,上传开始。

data.submit() 返回 Promise 对象,并且允许通过 jQuery 的 Deferred 回调向其附加其他操作。译者注:对应下面示例中 data.submit().success().error().complete(); 这样的链式操作。

add 回调函数会在 autoUpload 配置项设为 true 的时候(基础组件下的默认值)默认提交文件。当然对于在回调函数中 submit() 前面的程序,会在执行完之后才进行上传提交操作。

  • 默认值:
    function (e, data) {
        if (data.autoUpload || (data.autoUpload !== false &&
                $(this).fileupload('option', 'autoUpload'))) {
            data.process().done(function () {
                data.submit();
            });
        }
    }
  • 示例:
    function (e, data) {
        $.each(data.files, function (index, file) {
            console.log('Added file: ' + file.name);
        });
        data.url = '/path/to/upload/handler.json';
        var jqXHR = data.submit()
            .success(function (result, textStatus, jqXHR) {/* ... */})
            .error(function (jqXHR, textStatus, errorThrown) {/* ... */})
            .complete(function (result, textStatus, jqXHR) {/* ... */});
    }
submit

每个文件在上传时触发 submit 事件时的回调。

如果此回调返回 false,则不发送文件上传请求。

  • 示例:
    function (e, data) {
        var input = $('#input');
        data.formData = {example: input.val()};
        if (!data.formData.example) {
          data.context.find('button').prop('disabled', false);
          input.focus();
          return false;
        }
    }
send

每当有文件发送了上传请求时触发本回调函数。

如果本回调返回 false,那么文件上传请求会被中止。

  • 示例:
    function (e, data) {
        if (data.files.length > 10) {
            return false;
        }
    }
done

成功上传请求后调用。此回调函数等效于 jQuery ajax() 提供的 success 函数,即便服务端返回的 JSON 响应存在错误信息,都会触发本回调函数。译者注:只要响应的状态码 XMLHttpRequest.status 为 200,且响应的数据格式是 JSON 就会触发 done 回调。

  • 示例:
    function (e, data) {
        // data.result
        // data.textStatus;
        // data.jqXHR;
    }
fail

上传请求返回失败(中止或错误)的时候触发。此回调函数等效于 jQuery ajax() 的 .error()。若请求能够返回一个 JSON 响应,即便包含错误信息,都被认为是一个成功的 HTTP 响应,这种情况下不会触发 fail 回调。

  • 示例:
    function (e, data) {
        // data.errorThrown
        // data.textStatus;
        // data.jqXHR;
    }
always

上传请求结束后触发,不管是成功、中止还是错误。本回调相当于 jQuery ajax() 的 complete 函数。

  • 示例:
    function (e, data) {
        // data.result
        // data.textStatus;
        // data.jqXHR;
    }
progress

上传进度事件的回调。

  • 示例:
    function (e, data) {
        var progress = parseInt(data.loaded / data.total * 100, 10);
    }
progressall

全局上传进度事件的回调。

  • 示例:
    function (e, data) {
        var progress = parseInt(data.loaded / data.total * 100, 10);
    }
start

开始上传时触发,相当于 jQuery 的 ajaxStart 事件(仅适用于文件上传请求)。

  • 示例:
    function (e) {
        console.log('Uploads started');
    }
stop

上传请求完成时触发,相当于 jQuery 的 ajaxStop 事件(仅适用于文件上传请求)。

  • 示例:
    function (e) {
        console.log('Uploads finished');
    }
change

fileInput 对象触发 change 事件时调用。

  • 示例:
    function (e, data) {
        $.each(data.files, function (index, file) {
            console.log('Selected file: ' + file.name);
        });
    }
paste

设置了 dropZone 区域时,dropZone 对象触发 paste 事件时调用。

  • 示例:
    function (e, data) {
        $.each(data.files, function (index, file) {
            console.log('Pasted file type: ' + file.type);
        });
    }
drop

设置了 dropZone 区域时,dropZone 对象触发 drop 事件时调用。

  • 示例:
    function (e, data) {
        $.each(data.files, function (index, file) {
            console.log('Dropped file: ' + file.name);
        });
    }
dragover

定义了 dropZone 区域时,dropZone 对象触发 dragover 事件时调用。

要防止插件在源 dragover 事件对象上调用 preventDefault() 函数并将 dataTransfer.dropEffect 设为 copy,请在 fileuploaddragover 回调的事件上调用 preventDefault() 函数:

function (e, data) {
    e.preventDefault(); // Prevents the default dragover action of the File Upload widget
}
注意: 本插件之所以仅提供 dragover 回调,是因为上传功能只需要通过“拖”和“放”即可完成。如果你想要回调其他拖动事件,只需在 dropZone 对象上使用 jQuery 的原生事件绑定机制将需要的回调绑定到这些事件,例如:
$('#fileupload').on('dragleave', function (e) {
    // dragleave callback implementation
});
译者注:DataTransfer 对象用于保存在拖动与放下(dragdrop)的过程中的数据。其 dropEffect 属性用于获取当前选定的拖放操作类型或者设置的为一个新的类型。值必须为 none、copy、link 或 move:
  • none: 将任何值赋给 dropEffect 都没有效果。
  • copy: 在新位置生成源项的副本。
  • move: 将项目移到新位置。
  • link: 在新位置建立源项目的链接。
chunkbeforesend

分块上传,在每个分块上传请求开始前且表单数据初始化之前触发本回调。

chunksend

分块上传,在每个分块的表单数据初始化之后但是上传请求发送的前一刻调用本回调。

如果回调返回 false,那么该上传请求被中止。

chunkdone

分块上传请求成功后触发本回调。

chunkfail

分块上传请求失败(中止或错误)后触发本回调。

chunkalways

分块上传请求完成(成功、中止或错误)后触发本回调。

文件处理配置项


processQueue

文件处理操作的队列。译者注:$.blueimp.fileupload.prototype.options.processQueue

  • 类型:array
  • 默认值:[](空数组)
  • 示例:
    [
        {
            action: 'loadVideo',
            // Use the action as prefix for the "@" options:
            prefix: true,
            fileTypes: '@',
            disabled: '@disableVideoPreview'
        },
        {
            action: 'validate',
            // Always trigger this action,
            // even if the previous action was rejected: 
            always: true,
            acceptFileTypes: '@'
        }
    ]

队列数组的每个元素首先得是一个对象,我们称之为进程对象。每个进程对象必须拥有一个名为 action 而值为 string 类型的属性。

action 的取值必须是一个已定义的函数的函数名,该函数的原型对象为 $.blueimp.fileupload.prototype.processActions

例如 action: 'validate',那么在程序中就必须定义了一个 $.blueimp.fileupload.prototype.processActions.validate 函数。

译者注:插件的内置操作可以在每个组件中的 $.widget('blueimp.fileupload', $.blueimp.fileupload, {processActions: {}}; 查询到。内置操作包括:
  • jquery.fileupload-validate.js:validate。
  • jquery.fileupload-image.js:loadImage、resizeImage、saveImage、loadImageMetaData、saveImageMetaData、setImage、deleteImageReferences。
  • jquery.fileupload-audio.js:loadAudio、setAudio。
  • jquery.fileupload-video.js:loadVideo、setVideo。

在选定文件后开始文件处理时,每一个文件都会按顺序执行一遍队列中的各项操作。

在调用文件处理队列中的操作函数时,会传递两个参数:

  • data:本参数就是传递给 add 回调函数的 data 对象的 copy 副本,其中 data.files 指向 files 数组。
    此外,data 对象还有一个 index 属性,其值就是当前正在处理的文件在数组中的索引值。
  • options:当前处理操作的配置对象。

操作函数会将插件根元素设为 this 对象,而不是 processActions。这就允许在函数中通过 this.options 访问全局配置项。

操作函数要么返回一个 data 对象,要么返回一个 Promise 对象,其得注册以 data 对象为参数的解析函数(rewolveWith())或拒绝函数(rejectWith()译者注:也就是建一个 deferred 对象,然后把 data 作为参数传递给其解析函数和拒绝函数,最后这个 deferred 对象调用 promise() 函数作为 Promise 对象返回。

以一个简单的 validate 操作函数为例:

$.widget('blueimp.fileupload', $.blueimp.fileupload, {

    options: {
        acceptFileTypes: /(\.|\/)(gif|jpe?g|png)$/i,
        processQueue: {
            action: 'validate',
            acceptFileTypes: '@',
            disabled: '@disableValidation'
        }
    },

    processActions: {
        validate: function (data, options) {
            if (options.disabled) {
                return data;
            }
            var dfd = $.Deferred(),
                file = data.files[data.index];
            if (!options.acceptFileTypes.test(file.type)) {
                file.error = 'Invalid file type.';
                dfd.rejectWith(this, [data]);
            } else {
                dfd.resolveWith(this, [data]);
            }
            return dfd.promise();
        }
    }
});
@-Options

队列的每个进程对象中,任何属性值以“@”符号开头的属性都会遵循以下规则进行二次赋值:

  • 首先,移除字符串的“@”符号。
  • 得到的结果如果不为空,则将属性值设为与剩余字符串同名的全局配置项。例如,disabled: '@disableVideoPreview',则将全局配置项 disableVideoPreview 的值赋给 disabled 属性。
  • 如果剩余的是空字符串,那检查进程对象中有没有一个设为 true 的 prefix 属性:
    • 如果没有,那属性值设为与该属性同名的全局配置项。例如,acceptFileTypes: '@',那么 acceptFileTypes 属性设为全局 acceptFileTypes 配置。
    • 如果有,在该属性名前面加上进程对象的 action 属性值并按驼峰命名法得到一个临时名称,这时将属性值设为与临时名称同名的全局配置项。例如,来自前面示例中 loadVideo 进程对象的 fileTypes: '@',正如对象的 prefix 属性设为 true,所以其 fileTypes 属性最终设置为全局 loadVideoFileTypes 配置项的值。

文件处理回调函数


所有回调既可以是 function 类型,也可以绑定为事件侦听器,绑定为事件的时候在回调名称前加上“fileupload”作为前缀:

$('#fileupload')
    .on('fileuploadprocessstart', function (e) {/* ... */})
    .on('fileuploadprocess', function (e, data) {/* ... */})
    .on('fileuploadprocessdone', function (e, data) {/* ... */})
    .on('fileuploadprocessfail', function (e, data) {/* ... */})
    .on('fileuploadprocessalways', function (e, data) {/* ... */})
    .on('fileuploadprocessstop', function (e) {/* ... */});

需要注意的是,data 对象包含两个数组:

  • files - 包含队列操作处理后的文件列表。
  • originalFiles - 原始上传的文件列表。

它还包含一个索引参数,告诉你这次处理的是哪个文件。

processstart

整体的文件处理队列开始的回调。

  • 示例:
    function (e) {
        console.log('Processing started...');
    }
process

单个文件队列开始的回调。

  • 示例:
    function (e, data) {
        console.log('Processing ' + data.files[data.index].name + '...');
    }
processdone

单个文件处理队列成功完成的回调。

  • 示例:
    function (e, data) {
        console.log('Processing ' + data.files[data.index].name + ' done.');
    }
processfail

单个文件处理队列失败的回调。

  • 示例:
    function (e, data) {
        console.log('Processing ' + data.files[data.index].name + ' failed.');
    }
processalways

单个文件处理队列结束(完成或失败)的回调。

  • 示例:
    function (e, data) {
        console.log('Processing ' + data.files[data.index].name + ' ended.');
    }
processstop

整体的文件处理队列停止的回调。

  • 示例:
    function (e) {
        console.log('Processing stopped.');
    }

图片配置项(预览及调整大小)


disableImageHead

是否禁用解析和修改图像文件头。

  • 类型:boolean
  • 默认值:false
disableExif

是否禁用解析图像的 Exif 信息。译者注:Exif,全称 Exchangeable image file format,用来记录数码照片的属性信息和拍摄数据。

  • 类型:boolean
  • 默认值:false
disableExifOffsets

是否禁用 Exif 标签修改。

  • 类型:boolean
  • 默认值:false
includeExifTags

需要解析的 Exif 标签的映射表(默认包括所有标签除了被排除的之外)。

  • 类型:Object
  • 默认值:undefined
excludeExifTags

解析时需要排除的 Exif 标签的映射表(默认排除 MakerNotes 标签)。译者注:MakerNotes,用于记录相机各种拍摄参数的数据。

  • 类型:Object
  • 默认值:{ 0x8769: { 0x927c: true } }
disableIptc

是否禁用 IPTC 解析。译者注:IPTC,全称 International Press Telecommunications Council,可以将作者、版权、字幕、细节描述等 IPTC 元数据加入照片信息中。

  • 类型:boolean
  • 默认值:false
disableIptcOffsets

是否禁用 IPTC 标签修改。

  • 类型:boolean
  • 默认值:false
includeIptcTags

需要解析的 IPTC 标签的映射表(默认包括所有标签除了被排除的之外)。

  • 类型:Object
  • 默认值:undefined
excludeIptcTags

解析时需要排除的 IPTC 标签的映射表(默认排除 ObjectPreviewData 数据)。

  • 类型:Object
  • 默认值:{ 202: true }
disableImageMetaDataLoad

是否禁止解析图像元数据(图像文件头和 Exif 数据)。true 禁止,false 不禁止。

  • 类型:boolean
  • 默认值:false
disableImageMetaDataSave

是否禁止将图像元数据保存到调整了图像大小的文件中。

  • 类型:boolean
  • 默认值:false
loadImageFileTypes

本项是一条正则表达式,用于匹配需要加载的图像的文件类型。

  • 类型:正则表达式
  • 默认值:/^image\/(gif|jpeg|png)$/
loadImageMaxFileSize

图像大小上限,仅允许加载小于上限的图像。

  • 类型:integer
  • 默认值:10000000
loadImageNoRevoke

不要销毁用于加载图像的 URL 对象。

  • 类型:boolean
  • 默认值:false
disableImageLoad

是否禁止加载图像(并进行图像处理)。

  • 类型:boolean
  • 默认值:false
imageMaxWidth

调整图像大小时的最大宽度。

  • 类型:integer
  • 默认值:1920
imageMaxHeight

调整图像大小时的最大高度。

  • 类型:integer
  • 默认值:1080
imageMinWidth

调整图像大小时的最小宽度。

  • 类型:integer
  • 默认值:undefined
imageMinHeight

调整图像大小时的最小高度。

  • 类型:integer
  • 默认值:undefined
imageCrop

定义按哪种方式调整图像,裁剪或按比例缩放。true 表示裁剪,false 表示缩放。

  • 类型:boolean
  • 默认值:false
imageOrientation

定义图像旋转方向,取值范围 1 - 8,若值设为 true 则通过 Exif 数据获取。

  • 类型:integer or boolean
  • 默认值:true
imageForceResize

如果设为 true ,则强制通过 canvas 画布修改及保存图像,即便原图像自己都能满足所有修改条件。

  • 类型:integer or boolean
  • 默认值:undefined
disableImageResize

是否禁用调整图像大小功能。

  • 类型:boolean
  • 默认值:true
imageQuality

设置传递给 canvas.toBlob() 函数的图片品质参数,在保存已调整图像时会调用 toBlog() 函数。

  • 类型:float
  • 默认值:undefined
imageType

设置传递给 canvas.toBlob() 函数的图像类型参数。

  • 类型:string
  • 默认值:原始文件的图像类型,例如:image/jpeg
previewMaxWidth

预览图的最大宽度。

  • 类型:integer
  • 默认值:80
previewMaxHeight

预览图的最大高度。

  • 类型:integer
  • 默认值:80
previewMinWidth

预览图的最小宽度。

  • 类型:integer
  • 默认值:undefined
previewMinHeight

预览图的最小高度。

  • 类型:integer
  • 默认值:undefined
previewCrop

定义预览图的裁剪方式,裁剪或仅缩放。默认为 false 缩放,true 则表示裁剪。

  • 类型:boolean
  • 默认值:false
previewOrientation

定义预览图的旋转角度,取值范围 1 - 8,若设为 true 则通过 Exif 数据获取旋转信息。

  • 类型:integerboolean
  • 默认值:true
previewThumbnail

设为 true 则表示通过 Exif 数据的 thumbnail 字段来创建预览图。译者注:顾名思义,thumbnail 是嵌入在 TIFF 或 JPEG 图像中的缩略图

  • 类型:boolean
  • 默认值:true
previewCanvas

设为 true 表示将预览图以 canvas 画布元素方式进行大小调整。

  • 类型:boolean
  • 默认值:true
imagePreviewName

定义预览元素在 File 对象中的属性名。

  • 类型:string
  • 默认值:'preview'
disableImagePreview

是否禁用图像预览功能。

  • 类型:boolean
  • 默认值:false

音频预加载配置项


loadAudioFileTypes

本项是一条正则表达式,用于匹配需要加载的音频的文件类型。

  • 类型:正则表达式
  • 默认值:/^audio\/.*$/
loadAudioMaxFileSize

允许加载的音频文件的大小上限。

  • 类型:integer
  • 默认值:undefined
audioPreviewName

定义音频预加载元素在 File 对象中的属性名。

  • 类型:string
  • 默认值:'preview'
disableAudioPreview

是否禁用音频预加载功能。

  • 类型:boolean
  • 默认值:false

视频预加载配置项


loadVideoFileTypes

本项是一条正则表达式,用于匹配需要加载的视频的文件类型。

  • 类型:正则表达式
  • 默认值:/^video\/.*$/
loadVideoMaxFileSize

允许加载的视频文件的大小上限。

  • 类型:integer
  • 默认值:undefined
videoPreviewName

定义视频预加载元素在 File 对象中的属性名。

  • 类型:string
  • 默认值:'preview'
disableVideoPreview

是否禁用视频预加载功能。

  • 类型:boolean
  • 默认值:false

文件校验配置项


acceptFileTypes

校验文件属性的正则表达式,文件类型或文件名都需要匹配才允许上传。只有支持 File API 提示文件类型的浏览器才有效。

  • 类型:正则表达式
  • 默认值:undefined
  • 示例:/(\.|\/)(gif|jpe?g|png)$/i
maxFileSize

文件大小允许上传的上限。

  • 类型:integer
  • 默认值:undefined
  • 示例:10000000 // 10 MB
注意:该配置项只有在支持 File API 的浏览器下生效。
minFileSize

文件大小允许上传的下限。

  • 类型:integer
  • 默认值:undefined
  • 示例:1 // 1 Byte
注意:该配置项只有在支持 File API 的浏览器下生效。
maxNumberOfFiles

此配置项限制允许通过本插件上传的文件数量。

默认情况下,文件上传数量不受限制。

  • 类型:integer
  • 示例:10
注意:maxNumberOfFiles 配置项依赖 getNumberOfFiles 配置项。
disableValidation

是否禁用文件校验功能。

  • 类型:boolean
  • 默认值:false

UI 组件的附加配置项


getFilesFromResponse

从服务端响应的文件列表中,对文件进行二次处理的函数。

本函数会在触发 done 回调时,作为 data 参数传入回调,并在回调一开始对响应的文件进行处理。

函数返回值必须是一个数组。

  • 类型:function
  • 示例:function (data) {return data.result.files;}
getNumberOfFiles

本配置项是一个用于返回当前已选择并要上传的文件数量的函数。

它会在 maxNumberOfFiles 验证时被调用。

  • 类型:function
  • 示例:function () {return 5;}
filesContainer

上传 / 下载的文件列表的容器。

如果设置为 DOM 节点或字符串,则转换为 jQuery 对象

  • 类型:object
  • 默认值:widgetContainer.find('.files')
  • 示例:'#files'
prependFiles

默认情况下,文件都是按照 append 方式插入文件容器结尾。

将本配置项设为 true,则可改成 prepend 方式将文件插入容器开头。

  • 类型:boolean
  • 默认值:false
uploadTemplate

定义上传模板的函数,请参阅模板引擎

  • 类型:function
uploadTemplateId

上传模板的 id,作为参数传递给 tmpl() 方法以设置 uploadTemplate 配置项。

  • 类型:string
  • 默认值:'template-upload'
downloadTemplate

定义下载模板的函数,请参阅模板引擎

  • 类型:function
downloadTemplateId

下载模板的 id,作为参数传递给 tmpl() 方法以设置 downloadTemplate 配置项。

  • 类型:string
  • 默认值:'template-download'

UI 组件的附加回调函数


所有回调既可以是一个函数,也可以绑定为一个事件监听器。按照事件监听器方式时需要在回调名称前加上“fileupload”作为前缀:

$('#fileupload')
    .on('fileuploaddestroy', function (e, data) {/* ... */})
    .on('fileuploaddestroyed', function (e, data) {/* ... */})
    .on('fileuploaddestroyfailed', function (e, data) {/* ... */})
    .on('fileuploadadded', function (e, data) {/* ... */})
    .on('fileuploadsent', function (e, data) {/* ... */})
    .on('fileuploadcompleted', function (e, data) {/* ... */})
    .on('fileuploadfailed', function (e, data) {/* ... */})
    .on('fileuploadfinished', function (e, data) {/* ... */})
    .on('fileuploadstarted', function (e) {/* ... */})
    .on('fileuploadstopped', function (e) {/* ... */});
destroy

文件删除事件的回调。

注意:由于 UI 组件已经设置了这个回调配置项,建议使用 .on() 函数来附加事件监听。
  • 示例:
    function (e, data) {
        // data.context: download row,
        // data.url: deletion url,
        // data.type: deletion request type, e.g. "DELETE",
        // data.dataType: deletion response type, e.g. "json"
    }
  • 事件绑定示例:
    $('#fileupload')
        .on('fileuploaddestroy', function (e, data) {/* ... */});
destroyed

destroyed 回调相当于 destroy 回调,不过其在文件被删除、过渡效果完成后并且下载模板也被移除后触发。

destroyfailed

destroy 回调失败时调用 destroyfailed 函数,在文件不能被删除时触发。

added

added 回调相当于 add 回调,不过其在上传模板渲染完毕且过渡效果完成后触发。

sent

sent 回调相当于 send 回调,不过是在 send 回调已经执行但在文件将要发送前触发。

completed

completed 回调相当于 done 回调,不过是在上传成功、下载模板渲染完毕且过渡效果完成后触发。

failed

failed 回调相当于 fail 回调,不过是在上传失败、下载模板渲染完毕且过渡效果完成后触发。

finished

finished 回调相当于 always 回调,不过是在上传结束(成功或失败)、对应模板渲染完毕且过渡效果完成后触发。

started

started 回调相当于 start 回调,不过是在 start 回调已执行并且启动 start 回调的过渡效果完成后触发。

注意:started 回调和 start 回调不一样的一点,后者总是在所有 send 回调之前被调用,而 started 回调的调用时机取决于这些回调中过渡效果的持续时间,它有可能在 sent 回调之后才被调用。
stopped

stopped 回调相当于 stop 回调,不过是在 stop 回调执行之后以及 stop 和所有 done 回调的过渡效果完成之后触发。

因此,stopped 回调总会在每一次的 completed、failed 和 finished 回调之后被触发。