# 上传组件 Upload

# 引入

import { H3Upload } from '@lateinos/awesome-ui';

export default {
  components: {
    H3Upload,
  },
};

# 常规上传

# 限定文件大小

主要通过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 子配置项

如果 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 -
  • callback 子配置项
函数名 说明 参数
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: 移除文件事件}