上传组件

上传组件 upload 是用于处理文件上传的前端交互逻辑,可以更好地协助后端实现文件从本地到服务端上传的对接。

示例

以下示例均没有设置上传接口,因此每次上传都会报异常提示,这属于正常现象。实际使用时设置成您的真实上传接口即可。

图片上传

  

制作多文件上传表格

  

过滤文件类型

  

限制文件大小

  

选择后手动上传

  

拖拽上传

  

绑定原始文件域

  

API

API 描述
var upload = layui.upload 获得 upload 模块。
var inst = upload.render(options) upload 组件渲染,核心方法。
inst.upload() 对当前实例提交上传
inst.reload(options) 对当前实例进行重载
inst.config 获得当前实例的属性配置项

渲染

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);

该方法用于对当前的上传实例进行完整重载,所有属性均可参与到重载中。

// 渲染
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 组件支持跨域上传,一般有以下两种场景

  • 自建上传服务。在服务端配置 CORS 开启跨资源共享。 即对接口所在的服务器设置 Access-Control-Allow-Origin 相关 header 信息。

  • 第三方上传服务。如:阿里云、腾讯云等,只需按照不同平台对应的上传 SDK 进行操作即可。