Upload 上传

用于文件上传，支持按钮触发、拖拽上传、图片卡片等多种交互形式。

基础用法

最简单的文件上传，点击按钮选择文件。

拖拽上传

设置 drag 属性，将上传区域变为拖拽区域。

点击或拖拽文件到此区域上传

支持 jpg、png 格式，单文件不超过 5MB

拖拽上传

设置 drag 属性，将上传区域变为拖拽区域，可搭配 tip 显示提示信息。

点击或拖拽文件到此区域上传

支持 jpg、png 格式，单文件不超过 5MB

配置上传 API

设置 action 指定服务端接口地址，组件会使用 XMLHttpRequest 发送文件。支持 headers 设置请求头、data 附带额外参数、method 设置请求方法、name 设置文件字段名、withCredentials 携带 cookie。

文件将上传至 api.example.com

自定义上传逻辑

通过 custom-request 完全接管上传流程，适合对接 OSS、S3、微信云存储等第三方服务。回调函数接收 file（UploadFile 对象）、action、method、headers、data、onProgress、onSuccess、onError 参数。

自定义上传到云存储

手动上传

设置 auto-upload 为 false，用户选择文件后不会自动上传，需要通过 ref 调用 startUpload 方法手动触发。适合表单场景：先选择文件，填完表单后统一提交。

选择文件后点击下方按钮上传

上传前校验

通过 before-upload 钩子在上传前进行校验，返回 false 或 Promise reject 取消上传。支持异步校验（如检查文件内容、请求接口验证等）。

仅支持上传小于 2MB 的图片文件

多选与数量限制

设置 multiple 允许多选，limit 限制上传数量，超出触发 exceed 事件。

最多上传 3 个文件

图片列表模式

设置 list-type 为 picture，显示图片缩略图列表，点击缩略图可预览。

仅支持图片文件

照片墙模式

设置 list-type 为 picture-card，以卡片形式展示图片，支持预览和删除。

上传

文件大小与类型限制

设置 max-size 限制文件大小（单位字节），超出触发 error 事件。accept 限制可选择的文件类型。

仅支持 PDF/Word，单文件不超过 2MB

禁用状态

设置 disabled 禁用上传。

自定义触发

使用默认插槽自定义上传触发区域。

拖拽区自定义内容

使用 drag 插槽自定义拖拽区的展示内容。

将文件拖到此处

支持批量上传，严禁上传敏感数据

Props

属性	类型	默认值	说明
`modelValue`	`(string \| number)[]`	`[]`	已上传文件的 uid 列表（v-model）
`multiple`	`boolean`	`false`	是否允许多选文件
`accept`	`string`	`—`	接受的文件类型（MIME），picture/picture-card 模式默认 image/*
`disabled`	`boolean`	`false`	是否禁用上传
`drag`	`boolean`	`false`	是否启用拖拽上传区域
`limit`	`number`	`—`	最大上传数量限制
`autoUpload`	`boolean`	`true`	是否在选取文件后自动上传
`action`	`string`	`—`	上传地址，设置后使用 XMLHttpRequest 发送请求
`method`	`string`	`"POST"`	上传请求的 HTTP 方法
`headers`	`Record<string, string>`	`{}`	上传请求的自定义请求头
`data`	`Record<string, any>`	`{}`	上传请求附带的额外参数
`name`	`string`	`"file"`	上传文件的字段名
`withCredentials`	`boolean`	`false`	请求是否携带 cookie
`listType`	`'text' \| 'picture' \| 'picture-card'`	`'text'`	文件列表展示类型
`maxSize`	`number`	`—`	文件大小上限（字节），超出触发 error 事件
`tip`	`string`	`—`	提示文本
`buttonText`	`string`	`"上传文件"`	按钮文字
`dragText`	`string`	`"点击或拖拽文件到此区域上传"`	拖拽区域文字
`beforeUpload`	`(file: File, fileList: UploadFile[]) => boolean \| Promise<boolean>`	`—`	上传前钩子，返回 false 取消上传
`customRequest`	`(options: { file: UploadFile; action: string; method: string; headers: Record<string, string>; data: Record<string, any>; onProgress: (percent: number) => void; onSuccess: (response: any) => void; onError: (error: Error) => void }) => void`	`—`	自定义上传实现，接管整个上传流程，适合对接 OSS/S3/COS 等云存储

Events

事件名	参数	说明
`change`	`(fileList: UploadFile[])`	文件列表变化时触发
`success`	`(file: UploadFile, response: any)`	文件上传成功时触发
`error`	`(file: UploadFile, error: Error)`	文件上传失败时触发
`progress`	`(file: UploadFile, percent: number)`	文件上传进度变化时触发
`exceed`	`(files: File[])`	文件超出数量限制时触发
`preview`	`(file: UploadFile)`	点击文件预览时触发
`remove`	`(file: UploadFile)`	文件被删除时触发

Slots

插槽名	说明
`default`	自定义上传触发区域（仅非拖拽、非 picture-card 模式）
`drag`	自定义拖拽区域内容

Methods

方法名	类型	说明
`clearFiles`	`() => void`	清空文件列表
`startUpload`	`() => void`	手动开始上传所有待上传文件

UploadFile

属性	类型	说明
`uid`	`string`	文件唯一标识
`name`	`string`	文件名
`size`	`number`	文件大小（字节）
`status`	`'pending' \| 'uploading' \| 'done' \| 'error'`	文件状态
`progress`	`number`	上传进度（0-100）
`raw`	`File`	原始文件对象
`url`	`string`	文件 URL
`thumbUrl`	`string`	缩略图 URL
`response`	`any`	上传成功后服务端返回的响应数据