上传 Upload

用户头像上传

点击上传用户头像，可使用 beforeUpload 限制用户上传的图片格式和大小。

基本使用

上传组件的基本用法。

移除前校验

on-before-remove 会在每一个文件移除之前执行。如果返回 false 或者 Promise.reject，那么将会取消当前文件的操作。

上传前校验

beforeUpload 会在每一个文件上传之前执行。如果返回 false 或者 Promise.reject，那么将会取消当前文件的上传。

自定义上传节点

可以通过插槽 upload-button 传入自定义内容作为文件上传的触发节点。

自定义图标

文件夹上传

可以通过 directory 开启文件夹上传

拖拽上传

通过设置 draggable 开启对拖拽的支持。

限制上传数量

通过 limit 限制上传的最大数量。超出后上传按钮会隐藏.

跨标签页上传互斥

通过 lock-key 传入业务定义的互斥标识，例如用户 ID、用户名或上传任务 ID，组件不解释其含义。同源的标签页和组件实例中，相同 key 同时只允许一个文件上传，不同 key 可并行；未传入时不启用互斥。也可传入 (fileItem) => key 为每个文件计算标识，返回 undefined 表示该文件不加锁。空字符串仍是有效的锁标识。

锁被占用时，本次上传不会发送请求，也不会排队自动重传。文件状态变为 error，通过现有 error 事件返回 fileItem.response.code === 'UPLOAD_LOCK_BUSY'，可在原任务结束后手动重试。锁覆盖默认 XHR 和 custom-request，上传成功、失败、取消、移除或组件卸载后释放。每次开始上传时确定 key，修改 prop 不会迁移进行中的锁。

lock-key 为字符串时，该组件所有文件共用一个 key，因此批量上传时也会互斥。若业务允许不同任务并行，应通过函数返回各任务稳定的业务标识；不要使用组件自动生成的 uid 作为跨标签页任务标识。

此功能使用 Web Locks API，要求支持该 API 的安全上下文（HTTPS 或 localhost）。启用互斥但 API 不可用时，不发送请求，通过 error 事件返回 UPLOAD_LOCK_UNSUPPORTED；其他锁请求异常保留原始错误。自定义请求应在完成时调用 onSuccess / onError，并提供能实际终止传输的 abort，以便正确结束锁的生命周期。互斥仅协调同一浏览器存储分区内同源、使用相同 key 的上传，不记录已完成任务，也不替代服务端跨设备的幂等校验。

照片墙

通过设置 list-type="picture-card" 开启照片墙模式。

图标列表样式

通过设置 list-type="picture" 开启图片列表样式

自定义上传请求

可以通过 custom-request 实现自定义上传请求。

手动上传

设置 auto-upload 为 false 时候，可以通过调用 submit 方法进行手动上传。

已上传的文件列表

可以指定默认的已上传文件列表。

API

`<upload>` 属性

参数名	描述	类型	默认值	版本
file-list (v-model)	文件列表	`FileItem[]`	`-`
default-file-list	默认的文件列表（非受控状态）	`FileItem[]`	`[]`
accept	接收的上传文件类型，具体参考 HTML标准	`string`	`-`
action	上传的URL	`string`	`-`
disabled	是否禁用	`boolean`	`false`
multiple	是否支持多文件上传	`boolean`	`false`
directory	是否支持文件夹上传（需要浏览器支持）	`boolean`	`false`
draggable	是否支持拖拽上传	`boolean`	`false`
tip	提示文字	`string`	`-`
headers	上传请求附加的头信息	`Record<string, string>`	`-`
data	上传请求附加的数据	`Record<string, string \| Blob>\| ((fileItem: FileItem) => Record<string, string \| Blob>)`	`-`
name	上传的文件名	`string \| ((fileItem: FileItem) => string)`	`-`
with-credentials	上传请求是否携带 cookie	`boolean`	`false`
custom-request	自定义上传行为	`(option: RequestOption) => UploadRequest`	`-`
lock-key	跨标签页上传互斥标识；相同 key 同时只允许一个文件上传，函数返回 undefined 时不加锁	`string \| ((fileItem: FileItem) => string \| undefined)`	`-`
limit	限制上传文件的数量。`0`表示不限制	`number`	`0`
auto-upload	是否自动上传文件	`boolean`	`true`
show-file-list	是否显示文件列表	`boolean`	`true`
show-remove-button	是否显示删除按钮	`boolean`	`true`	2.11.0
show-start-button	是否显示开始按钮	`boolean`	`true`
show-retry-button	是否显示重试按钮	`boolean`	`true`	2.11.0
show-cancel-button	是否显示取消按钮	`boolean`	`true`	2.11.0
show-upload-button	是否显示上传按钮。2.14.0 版本新增 `showOnExceedLimit` 支持	`boolean \| { showOnExceedLimit: boolean }`	`true`	2.11.0
show-preview-button	照片墙是否显示预览按钮	`boolean`	`true`	2.42.0
download	是否在 `<a>` 链接上添加 download 属性	`boolean`	`false`	2.11.0
show-link	在列表模式下，如果上传的文件存在 URL 则展示链接。如果关闭仅展示文字并且点击可以触发 `preview` 事件。	`boolean`	`true`	2.13.0
image-loading	`__SD_PLACEHOLDER_0__` 的原生 HTML 属性，需要浏览器支持	`'eager' \| 'lazy'`	`-`	2.11.0
list-type	图片列表类型	`'text' \| 'picture' \| 'picture-card'`	`'text'`
response-url-key	Response中获取图片URL的key，开启后会用上传的图片替换预加载的图片	`string \| ((fileItem: FileItem) => string)`	`-`
custom-icon	自定义图标	`CustomIcon`	`-`
image-preview	是否使用 ImagePreview 组件进行预览	`boolean`	`false`	2.14.0
on-before-upload	上传文件前触发	`(file: File) => boolean \| File \| Promise<boolean \| File>`	`-`
on-before-remove	移除文件前触发	`(fileItem: FileItem) => Promise<boolean>`	`-`
on-button-click	点击上传按钮触发（如果返回 Promise 则会关闭默认 input 上传）	`(event: Event) => Promise<FileList> \| void`	`-`

`<upload>` 事件

事件名	描述	参数
exceed-limit	上传的文件超出限制后触发	fileList: `FileItem[]` files: `File[]`
change	上传的文件状态发生改变时触发	fileList: `FileItem[]` fileItem: `fileItem`
progress	上传中的文件进度改变时触发	fileItem: `fileItem` ev: `ProgressEvent`
preview	点击图片预览时的触发	fileItem: `FileItem`
success	上传成功时触发	fileItem: `FileItem`
error	上传失败时触发	fileItem: `FileItem`

`<upload>` 方法

方法名	描述	参数	返回值	版本
submit	上传文件（已经初始化完成的文件）	fileItem: `FileItem`	-
abort	中止上传	fileItem: `FileItem`	-
updateFile	更新文件	id: `string` file: `File`	-
upload	上传文件	files: `File[]`	-	2.41.0

`<upload>` 插槽

插槽名	描述	参数	版本
extra-button	上传列表额外按钮	fileItem: `FileItem`	2.43.0
image	自定义图片	fileItem: `FileItem`	2.23.0
file-name	文件名称	fileItem: `FileItem`	2.23.0
file-icon	文件图标	fileItem: `FileItem`	2.23.0
remove-icon	删除图标	-	2.23.0
preview-icon	预览图标	-	2.23.0
cancel-icon	取消图标	-	2.23.0
start-icon	开始图标	-	2.23.0
error-icon	失败图标	-	2.23.0
success-icon	成功图标	-	2.23.0
retry-icon	重试图标	-	2.23.0
upload-button	上传按钮	-
upload-item	上传列表的项目	fileItem: `FileItem` index: `number`

FileItem

参数名	描述	类型	默认值
uid	当前上传文件的唯一标示	`string`	`-`
status	当前上传文件的状态	`FileStatus`	`-`
file	文件对象	`File`	`-`
percent	上传进度百分比	`number`	`-`
response	当前文件上传请求返回的响应	`any`	`-`
url	文件地址	`string`	`-`
name	文件名	`string`	`-`

CustomIcon

参数名	描述	类型	默认值
startIcon	开始图标	`RenderFunction`	`-`
cancelIcon	取消图标	`RenderFunction`	`-`
retryIcon	重试图标	`RenderFunction`	`-`
successIcon	成功图标	`RenderFunction`	`-`
errorIcon	失败图标	`RenderFunction`	`-`
removeIcon	移除图标	`RenderFunction`	`-`
previewIcon	预览图标	`RenderFunction`	`-`
fileIcon	文件图标	`(fileItem: FileItem) => VNode`	`-`
fileName	文件名	`(fileItem: FileItem) => string \| VNode`	`-`

RequestOption

参数名	描述	类型	默认值
action	上传的URL	`string`	`-`
headers	请求报文的头信息	`Record<string, string>`	`-`
name	上传文件的文件名	`string \| ((fileItem: FileItem) => string)`	`-`
fileItem	上传文件	`FileItem`	`-`
data	附加的请求信息	`Record<string, string \| Blob> \| ((fileItem: FileItem) => Record<string, string \| Blob>)`	`-`
withCredentials	是否携带cookie信息	`boolean`	`false`
onProgress	更新当前文件的上传进度。percent: 当前上传进度百分比	`(percent: number, event?: ProgressEvent) => void`	`-`
onSuccess	上传成功后，调用onSuccess方法，传入的response参数将会附加到当前上传文件的response字段上	`(response?: any) => void`	`-`
onError	上传失败后，调用onError方法，传入的response参数将会附加到当前上传文件的response字段上	`(response?: any) => void`	`-`

UploadRequest

参数名	描述	类型	默认值
abort	终止上传	`() => void`	`-`