上传组件
上传组件 upload 是用于处理文件上传的前端交互逻辑，可以更好地协助后端实现文件从本地到服务端上传的对接。
示例
以下示例均没有设置上传接口，因此每次上传都会报异常提示，这属于正常现象。实际使用时设置成您的真实上传接口即可。
图片上传
制作多文件上传表格
过滤文件类型
限制文件大小
选择后手动上传
拖拽上传
API
渲染
upload.render(options);
- 参数
options : 基础属性选项。#详见属性
注 : 除 elem 属性外，其他基础属性也可以直接写在元素的 lay-options="{}" 属性中。
<button type="button" class="layui-btn" id="ID-test-uoload">上传</button>
<button type="button" class="layui-btn test-class-upload" lay-options="{}">上传</button>
<button type="button" class="layui-btn test-class-upload" lay-options="{}">上传</button>
<!-- import layui -->
<script>
layui.use(function(){
var upload = layui.upload;
// 单个渲染
upload.render({
elem: '#ID-test-uoload',
// …
});
// 批量渲染
upload.render({
elem: '.test-class-upload',
// …
});
});
</script>
该方法返回一个实例对象，包含操作当前实例的相关方法成员。
var inst = upload.render(options);
console.log(inst); // 得到当前实例对象
提交上传
inst.upload();
文件在进行选择后，会自动提交上传。而若文件上传失败，则可以使用该方法来重新上传，
// 渲染
var inst = upload.render({
elem: '#id',
error: function(){ // 上传失败的回调
// 当上传失败时，可在此处生成「重新上传」按钮，并执行该方法重新触发上传提交
/*
$('#btn').on('click', function(){
inst.upload();
})
*/
}
// …
});
重载
inst.reload(options);
- 参数
options : 基础属性选项。#详见属性
该方法用于对当前的上传实例进行完整重载，所有属性均可参与到重载中。
// 渲染
var inst = upload.render({
elem: '#id',
// …
});
// 重载
inst.reload({
field: 'AAA',
// …
})
属性
| 属性名 |
描述 |
类型 |
默认值 |
| elem |
绑定元素选择器或 DOM 对象
|
string/DOM |
- |
| url |
上传接口
|
string |
- |
| field |
文件域的字段名
|
string |
file
|
|
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
|
指定允许上传时校验的文件类型。可选值有：
images 图片类型file 所有文件类型video 视频类型audio 音频类型
|
string |
images
|
| acceptMime |
规定打开系统的文件选择框时，筛选出的文件类型，多个 MIME 类型可用逗号隔开。示例：
acceptMime: 'image/*'` // 筛选所有图片类型
acceptMime: 'image/jpeg, image/png` // 只筛选 jpg,png 格式图片
更多可选值参考: MIME 类型
|
string |
- |
|
exts
|
允许上传的文件后缀。一般结合 accept 属性来设定。
- 假设
accept: 'file' 类型时，那么设置 exts: 'zip|rar|7z' 即代表只允许上传压缩格式的文件。
- 默认为常见图片后缀，即
jpg|png|gif|bmp|jpeg|svg
|
string |
见左
|
| auto |
是否选完文件后自动上传。若为 false，则需设置 bindAction 属性来指向其它按钮提交上传。参考：#示例
|
boolean |
true
|
| bindAction |
设置触发上传的元素选择器或 DOM 对象。
一般配合 auto: false 来使用。详细用法参考：#示例
|
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 2.8.9+
|
text: { // 自定义提示文本
"data-format-error": "", // 数据格式错误的提示
"check-error": "", // 文件格式校验失败的提示
"error": "", // 上传失败的提示
"limit-number": null, // 限制 number 属性的提示。若设置，需为函数写法
"limit-size": null, // 限制 size 属性的提示。若设置，需为函数写法
"cross-domain": "", // IE 下跨域的提示
}
|
|
|
|
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();
详细用法参考：#示例
|
|
before
|
文件提交上传前的回调函数。返回的参数同 choose
before: function(obj){ // obj 参数同 choose
layer.load(); // 上传 loading
// 若返回 false，则表明阻止上传
/*
if(true){
return false;
}
*/
}
// 返回 jQuery Deferred 对象或 JS 原生 Promise 对象，false 或 Promise.reject 表明阻止上传(2.9.11+)
// Promise
/** @type {(obj: object) => boolean | JQueryDeferred<boolean> | Promise<boolean>} */
before: function(obj){
return new Promise(function(resolve, reject){
setTimeout(function(){
console.log('before_async_task', obj);
resolve(true);
}, 1000)
})
}
// Deferred
before: function(obj){
return $.Deferred(function(defer){
setTimeout(function(){
console.log('before_async_task', obj);
defer.resolve(true);
}, 1000)
}).promise();
}
// Deferred2
before: function(obj){
var defer = $.Deferred();
setTimeout(function(){
console.log('before_async_task', obj);
defer.resolve(true);
}, 1000)
return defer.promise();
}
|
|
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 + '%'); // 进度条
}
详细用法参考：#示例
|
|
done
|
执行单次文件上传请求后的回调函数。返回的参数如下：
done: function(res, index, upload){
// 假设 `code: 0` 代表上传成功
if(res.code == 0){
// do something // 比如将 res 返回的图片链接保存到隐藏域
}
// 获取当前触发上传的元素，一般用于 elem 绑定 class 的情况
var item = this.item;
// …
}
详细用法参考：#示例
|
|
allDone
|
当开启多文件 (multiple: true ) 且所有文件均上传完毕后的状态回调函数。
allDone: function(obj){
console.log(obj.total); // 上传的文件总数
console.log(obj.successful); // 上传成功的文件数
console.log(obj.failed); // 上传失败的文件数
}
|
| error |
执行上传请求出现异常的回调（一般为网络异常、URL 404等）。返回三个参数如下：
index： 当前文件的索引upload： 重新上传的方法res： 返回值（纯文本）2.9.12+xhr: jQuery XHR 对象 2.9.15+
error: function(index, upload, res, xhr){
console.log(index); // 当前文件的索引
// upload(); 重新上传的方法
console.log(res); // 返回值（纯文本）
console.log(JSON.parse(res)); // 返回值（json）
console.log(xhr);
}
|
跨域方案
upload 组件支持跨域上传，一般有以下两种场景
