上传组件 Upload
引入
常规上传
限定文件大小
主要通过maxSize
控制,通过oversize
事件捕获
限定文件格式
比如图片格式仅gif,jpeg
限制上传个数
主要通过limit
控制,通过exceed
事件捕获
钩子拦截
比如举个删除前的拦截,允许接受两种状态去拦截。true/false
orPromise.reject
,
只读模式
也可以理解为查看模式,主要是通过disabled
这个props
,
API
- 本文中所有的原始文件对象统称为
原始文件
,而经过包装后的文件对象称为文件对象
,这个文件对象的结构如下
属性 | 说明 | 类型 | prop:value 必填项 |
uid | uid | string | 否 |
name | 文件名 | string | 是,应带文件后缀,若无文件后缀,请设置 category |
type | 文件原始类型 | number | 否 |
size | 文件大小 | number | 否 |
category | 文件类别 image video audio document word excel ppt pdf archive exe unknown | number | 否 |
categoryIcon | 文件类别缩略图 | string | 否 |
url | 文件 url,通过 URL.createObjectURL 获得,或者是 prop:value 传入的url | string | 是 |
previewUrl | 图片预览大图地址 | string | 否 |
status | 文件状态,ready , uploading , success , error , finish | string | 否 |
progress | 文件上传进度,整数 0~100 | number | 否 |
file | 原始文件或者 prop:value 传入的对象 | File | object | 否 |
base64 | 文件转成base64字符串,仅仅在prop:base64 非否时产生 | string | 否 |
previewable | 是否可以预览,默认可以 | boolean | 否 |
downloadable | 是否可以下载,默认可以 | boolean | 否 |
base64 | 文件转成base64字符串,仅仅在prop:base64 非否时产生 | boolean | 否 |
result | 响应内容,上传成功或失败后产生 | any | 否 |
Prop
属性 | 说明 | 类型 | 默认值 |
value | value,v-model 绑定值,子配置项可参考 文件对象 结构中 prop:value 必填项描述 | array | 无 |
mode | 模式 详情模式 'detail' 和 简单模式 'simple' | string | 'detail' |
simpleSize | 简单模式下尺寸 | number | 36 |
zIndex | 图片弹窗的z-index | number | 1500 |
placeholder | 提示文本 | string | '点击或拖拽文件上传' |
action | 上传行为配置项,最少包含上传目标的 URL 地址 | string | object | 无 |
request | 上传请求函数,参数 file: 文件对象 , action: 处理过的prop:action , callback: 回调函数对象 {onSuccess, onError, onProgress} | function | 内置上传函数 |
accept | 允许上传的文件类型,详细说明 (opens new window) | string | '*' |
multiple | 是否允许多选 | boolean | false |
parallelCount | 并行上传文件数量 | number | 5 |
limit | 上传文件限制数量 | string |number | - |
format | 匹配的文件后缀的数组,例如['png','jpeg','jpg'] ;或者是返回boolean的函数,若为返回true则为匹配,false为不匹配,参数是原始文件 | array| function | [] |
maxSize | 文件最大尺寸,单位为 byte | string |number | - |
disabled | 是否禁用 | boolean | false |
deletable | 是否可删除 | boolean | true |
previewable | 文件列表是否可以预览 | boolean | true |
downloadable | 文件列表是否可以下载 | boolean | true |
uploadIcon | 默认的上传按钮icon | string | plus-o |
processFile | 添加文件到列表时触发文件处理函数,请返回处理后的文件对象 ;若返回false可终止文件读取;若返回Promise 请在成功回调返回处理后的文件对象 ;参数是文件对象 | function | - |
thumbnail | 图片类型的文件是否展示实际图片缩略图而非文件类别缩略图 | boolean | true |
excludeThumbnail | 排除那些图片类型展示实际图片缩略图, ['gif'] | array | [] |
customize | 是否自定义触发选择文件而非使用浏览器默认调用,若为 true 请监听 event:select 事件及调用实例方法 addFiles | boolean | false |
base64 | 是否将文件转成base64字符串,若为true 则所有类型的文件都会被转换,若为数组,则只对指定的文件类型category 做转换,例如 ['image'] | boolean|array | false |
beforeRemove | 删除文件之前的钩子,参数为上传的文件和文件列表,若返回 false 或者返回 Promise 且被 reject,则停止删除。 function(file, fileList) | function | - |
如果 action
是字符串,则会被处理成 { target: action }
。
参数 | 说明 | 类型 | 默认值 |
target | 上传目标 URL,如果为函数,则传入当前文件对象 调用得到目标 URL | string | function | - |
fileName | 上传文件时文件的参数名 | string | 'file' |
prop | 上传的时候使用文件对象的 prop 属性所对应的值 | string | 'file' |
headers | 自定义请求头,如果为函数,则传入当前文件对象 调用得到 headers | object | function | {} |
data | 上传需要附加数据,如果为函数,则传入当前文件对象 调用得到 data | object | function | {} |
withCredentials | 标准的 CORS 请求是不会带上 cookie 的,如果想要带的话需要设置 withCredentials 为 true | boolean | false |
timeout | 请求超时时间 | number | 0 |
handleResult | 处理返回结果的函数,返回值会赋值到文件对象 的result,失败的处理尽量为string 类型及具体的描述 | (target, xhr) => any | - |
函数名 | 说明 | 参数 |
onSuccess | 当成功时调用 | function |
onError | 当失败时调用 | function |
onProgress | 当加载时能获取上传进度时调用 | function |
Event
事件名 | 说明 | 参数 |
input | 文件列表改变时触发,v-model 绑定事件 | value:文件对象 [] |
exceed | 上传文件数量超过限制时触发 | selectFiles:文件对象 [],当前选中的文件,files:文件对象 [],当前文件列表数据,limit:number 上传文件限制数量 |
mismatch | 上传文件匹配后缀类型错误时触发 | mismatchFiles:文件对象 [],格式匹配错误文件,selectFiles:文件对象 [],当前选中的文件,format:array 文件格式数组 |
oversize | 上传文件大小超过限制时触发 | oversizeFiles:文件对象 [],超过大小限制的文件,selectFiles:文件对象 [],当前选中的文件,maxSize:number 文件最大尺寸 |
success | 单个文件上传成功时触发 | result: 响应内容, file:文件对象 ,对应的文件 |
error | 单个文件上传失败时触发 | result: 错误对象或描述,file:文件对象 ,对应的文件 |
progress | 文件上传过程有进度时触发 | percent: 进度[0 - 100],file:文件对象 ,对应的文件 |
done | 全部文件上传完后触发,无论是否上传失败 | files:文件对象 [] |
removed | 文件要被移除后触发 | file:文件对象 , 被移除的文件, index: 下标 , files:文件对象 [],当前文件列表数据 |
fileClick | 文件列表项被点击触发 | file:文件对象 , index: 下标 , 被点击的文件,files:文件对象 [], 当前文件列表数据 |
select | 自定义选择文件时触发 | - |
preview | 点击文件链接或预览文本时的回调 | file:文件对象 , index: 下标 , files:文件对象 [] 当前文件列表数据 |
download | 自定义下载时点击下载文本时的回调 | file:文件对象 , index: 下标 , files:文件对象 [] 当前文件列表数据 |
Function
方法名 | 说明 | 参数 |
start | 开始上传 | - |
pause | 暂停上传 | - |
retry | 重试上传 | - |
removeFile | 删除文件 | 文件对象 |
addFiles | 添加文件 | 原始文件 [] |
Slots
参数 | 说明 | SlotProps |
default | 上传按钮插槽 | - |
list | 文件列表插槽 | {files: 文件列表, removeFile: 移除文件事件} |