属性名 描述 类型 默认值
elem 绑定元素选择器或 DOM 对象 string/DOM -
url 上传接口 string -
field 文件域的字段名 string `file`
[data](#options.data)
传递给上传接口的额外参数,支持静态赋值和动态赋值两种写法。
- 静态赋值 : ``` data: { id: '123' } ``` - 动态赋值 : ``` data: { id: function(){ return $('#id').val(); }, id2: function(index, file){ // 参数支持。2.9.3+ // 注:当 unified:true 和 ie8/9 下,参数无效 console.log(index); // 得到文件索引 console.log(file); // 得到文件对象 } } ```
object -
headers 上传接口的请求头。如 `headers: {token: 'abc123'}` object -
dataType 2.8.17+ 服务端返回的数据类型,如:`text,json,xml` 等 string `json`
[accept](#options.accept)
指定允许上传时校验的文件类型。可选值有:
- `images` 图片类型 - `file` 所有文件类型 - `video` 视频类型 - `audio` 音频类型
string `images`
acceptMime 规定打开系统的文件选择框时,筛选出的文件类型,多个 `MIME` 类型可用逗号隔开。示例: ``` acceptMime: 'image/*'` // 筛选所有图片类型 acceptMime: 'image/jpeg, image/png` // 只筛选 jpg,png 格式图片 ``` 更多可选值参考: MIME 类型 string -
[exts](#options.exts)
允许上传的文件后缀。一般结合 `accept` 属性来设定。
- 假设 `accept: 'file'` 类型时,那么设置 `exts: 'zip|rar|7z'` 即代表只允许上传压缩格式的文件。 - 默认为常见图片后缀,即 `jpg|png|gif|bmp|jpeg|svg`
string 见左
auto 是否选完文件后自动上传。若为 `false`,则需设置 `bindAction` 属性来指向其它按钮提交上传。参考:[#示例](#demo-auto) boolean `true`
bindAction 设置触发上传的元素选择器或 DOM 对象。
一般配合 `auto: false` 来使用。详细用法参考:[#示例](#demo-auto)
string/DOM -
force 2.6.9+ 规定强制返回的数据格式。 - 若值为 `'json'`,则强制校验 JSON 数据格式 string `null`
size 设置文件最大可允许上传的大小,单位 `KB` 。默认不限制。
不支持 `ie8/9`
number `0`
multiple 是否允许多文件上传。不支持 `ie8/9` boolean `false`
unified 2.8.8+ 选择多文件时,是否统一上传,即只发送一次请求。 boolean `false`
number 同时可上传的文件数量,一般当 `multiple: true` 时使用。 number -
drag 是否接受拖拽的文件上传。 boolean `true`
[text](#options.text) 2.8.9+
自定义内部各类场景下的提示文本
``` text: { // 自定义提示文本 "data-format-error": "", // 数据格式错误的提示 "check-error": "", // 文件格式校验失败的提示 "error": "", // 上传失败的提示 "limit-number": null, // 限制 number 属性的提示。若设置,需为函数写法 "limit-size": null, // 限制 size 属性的提示。若设置,需为函数写法 "cross-domain": "", // IE 下跨域的提示 } ```
[回调函数](#options.callback)
[choose](#options.choose)
选择文件后的回调函数。返回的参数如下
``` choose: function(obj){ // 将每次选择的文件追加到文件队列 var files = obj.pushFile(); // 预读本地文件,如果是多文件,则会遍历。(不支持ie8/9) obj.preview(function(index, file, result){ console.log(index); // 得到文件索引 console.log(file); // 得到文件对象 console.log(result); // 得到文件base64编码,比如图片 // obj.resetFile(index, file, '123.jpg'); // 重命名文件名 // 这里还可以做一些 append 文件列表 DOM 的操作 // obj.upload(index, file); // 对上传失败的单个文件重新上传,一般在某个事件中使用 // delete files[index]; //删除列表中对应的文件,一般在某个事件中使用 }); } // 获取本次选取的文件,大文件建议用此方法获取文件信息(2.9.9+) obj.getChooseFiles(); ``` 详细用法参考:[#示例](#demo-files-table)
[before](#options.before)
文件提交上传前的回调函数。返回的参数同 choose
``` before: function(obj){ // obj 参数同 choose layer.load(); // 上传 loading // 若返回 false,则表明阻止上传 /* if(true){ return false; } */ } ```
[progress](#options.progress)
执行上传请求后的回调函数。返回的参数如下:
``` progress: function(n, elem, res, index){ var percent = n + '%' // 获取进度百分比 element.progress('demo', percent); // 可配合 layui 进度条元素使用 // 得到当前触发的元素 DOM 对象 console.log(elem); // 可通过该元素定义的属性值匹配到对应的进度条。 console.log(res); // 得到 progress 响应信息 console.log(index); // 得到当前上传文件的索引,多文件上传时的进度条控制 element.progress('demo-'+ index, n + '%'); // 进度条 } ``` 详细用法参考:[#示例](#examples)
[done](#options.done)
执行单次文件上传请求后的回调函数。返回的参数如下:
``` done: function(res, index, upload){ // 假设 `code: 0` 代表上传成功 if(res.code == 0){ // do something // 比如将 res 返回的图片链接保存到隐藏域 } // 获取当前触发上传的元素,一般用于 elem 绑定 class 的情况 var item = this.item; // … } ``` 详细用法参考:[#示例](#examples)
[allDone](#options.allDone)
当开启多文件 (`multiple: true` ) 且所有文件均上传完毕后的状态回调函数。
``` allDone: function(obj){ console.log(obj.total); // 上传的文件总数 console.log(obj.successful); // 上传成功的文件数 console.log(obj.failed); // 上传失败的文件数 } ```
error 执行上传请求出现异常的回调(一般为网络异常、URL 404等)。返回两个参数如下: ``` error: function(index, upload){ console.log(index); // 当前文件的索引 // upload(); 重新上传的方法 } ```