Upload 上传

用于文件上传，支持按钮触发、拖拽上传、图片卡片等多种交互形式。另有 ImageUpload 专门用于单图片上传场景。

综合示例

完整演示：配置上传接口、文件列表、成功/失败回调、删除确认弹窗等。

基础用法

最简单的文件上传，点击按钮选择文件即可。不设置 action 时使用模拟上传。

配置上传接口

设置 action 指定服务端地址，组件使用 XMLHttpRequest 发送文件。支持 headers（请求头）、data（额外参数）、name（字段名）、withCredentials（携带 cookie）等配置。

文件将上传至 api.example.com

自定义上传逻辑

通过 custom-request 接管上传流程，适合对接 OSS、S3、COS 等云存储。回调参数含 file、onProgress、onSuccess、onError。

自定义上传到云存储

拖拽上传

设置 drag 启用拖拽区域，搭配 tip 显示提示信息。

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

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

拖拽区自定义内容

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

将文件拖到此处

支持批量上传

手动上传

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

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

上传前校验

通过 before-upload 钩子在上传前校验，返回 false 取消上传。支持异步校验。

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

多选与数量限制

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

最多上传 3 个文件

图片列表模式

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

仅支持图片文件

照片墙模式

设置 list-type=picture-card，以卡片网格展示图片，hover 可预览/删除。

上传

文件大小与类型限制

max-size 限制大小（字节），accept 限制类型，超出触发 error 事件。

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

禁用状态

设置 disabled 禁用上传。

自定义触发按钮

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

ImageUpload 单图片上传

专门用于单图片上传场景，v-model 绑定图片 URL，内置预览/删除功能，支持自定义上传逻辑。

基础用法

通过 v-model 绑定图片 URL，选择图片后自动展示预览，可点击预览大图、删除重新上传。

上传图片

图片 URL：未上传

配置上传接口

设置 action 后，选择图片会通过 XMLHttpRequest 上传到服务端，v-model 绑定服务端返回的图片 URL。

上传图片

自定义尺寸

通过 width 和 height 设置预览框尺寸，tip 设置提示文字。

头像

封面图

上传前校验

通过 before-upload 校验文件类型和大小，max-size 限制大小。

不超过 2MB

自定义上传

通过 custom-request 接管上传，适合对接云存储。

上传图片

禁用状态

设置 disabled 禁用上传和删除。

Upload Props

参数	类型	默认值	说明
`modelValue`	`(string \| number)[]`	`[]`	已上传文件的 uid 列表（v-model）
`multiple`	`boolean`	`false`	是否允许多选文件
`accept`	`string`	`—`	接受的文件类型（MIME），picture 模式默认 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) => void`	`—`	自定义上传实现，适合对接云存储

Upload Events

事件名	参数	说明
`update:modelValue`	`(uids: (string\|number)[])`	文件 uid 列表变化时触发
`update:fileList`	`(fileList: UploadFile[])`	文件列表变化时触发
`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)`	文件被删除

Upload Slots

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

Upload 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`	服务端响应数据

ImageUpload Props

参数	类型	默认值	说明
`modelValue`	`string`	`''`	图片 URL（v-model）
`action`	`string`	`—`	服务端上传地址
`method`	`string`	`'POST'`	HTTP 请求方法
`headers`	`Record<string, string>`	`{}`	自定义请求头
`data`	`Record<string, any>`	`{}`	上传附带额外参数
`name`	`string`	`'file'`	上传文件字段名
`withCredentials`	`boolean`	`false`	是否携带 cookie
`customRequest`	`(options) => void`	`—`	自定义上传实现
`beforeUpload`	`(file: File) => boolean \| Promise<boolean>`	`—`	上传前钩子
`maxSize`	`number`	`—`	文件大小上限（字节）
`accept`	`string`	`'image/*'`	接受的文件类型
`disabled`	`boolean`	`false`	是否禁用
`width`	`number \| string`	`104`	预览框宽度
`height`	`number \| string`	`104`	预览框高度
`tip`	`string`	`'上传图片'`	提示文字

ImageUpload Events

事件名	参数	说明
`update:modelValue`	`(url: string)`	图片 URL 变化时触发
`change`	`(url: string)`	图片 URL 变化时触发
`success`	`(response: any)`	上传成功时触发
`error`	`(error: Error)`	上传失败或校验不通过时触发
`progress`	`(percent: number)`	上传进度变化时触发
`remove`	`()`	图片被删除时触发

ImageUpload Slots

插槽名	说明
`default`	自定义上传触发区域内容（未上传时）