官方文档 https://element-plus.org/zh-CN/component/upload
el-upload 控件完整功能手册
从属性 (Attributes)、生命周期钩子/事件 (Events)、插槽 (Slots) 和方法 (Methods) 四个方面解析el-upload控件。
1. 属性 (Attributes) - 控制组件行为与外观
| 属性 (Attribute) | 类型 (Type) | 说明与核心用途 |
|---|---|---|
| 核心功能 | ||
action |
string |
必填，上传的目标服务器 URL 地址。 |
v-model:file-list |
array |
绑定文件列表，实现对列表的完全控制（加载、删除、更新）。 |
name |
string |
上传文件时，文件在表单中的字段名。默认为 file。可以设置为 files[] 以支持多文件数组。 |
:data |
object |
上传时需要额外附加的表单参数，如 article_id。 |
| HTTP 请求控制 | ||
:headers |
object |
设置自定义请求头，常用于传递 Authorization Token 进行身份验证。 |
:http-request |
function |
最强自定义功能。覆盖默认的上传行为，允许你使用 axios 或其他库实现自己的上传逻辑（如分片上传、获取S3签名等）。 |
:with-credentials |
boolean |
是否在跨域请求中携带 cookie，默认为 false。 |
| 上传行为控制 | ||
:auto-upload |
boolean |
是否在选择文件后立即自动上传，默认为 true。设为 false 可实现手动上传。 |
multiple |
boolean |
是否支持同时选择多个文件，默认为 false。 |
drag |
boolean |
是否启用拖拽上传，默认为 false。 |
disabled |
boolean |
是否禁用整个上传组件，默认为 false。 |
| 文件限制与校验 | ||
accept |
string |
接受上传的文件类型，会影响文件选择窗口的过滤器。例如：image/jpeg, image/png。 |
limit |
number |
允许上传的最大文件数量。 |
| 外观与交互 | ||
list-type |
string |
文件列表的显示样式，可选值为 text (默认), picture, picture-card (常用于照片墙)。 |
:show-file-list |
boolean |
是否显示内置的文件列表，默认为 true。在使用自定义列表时，应设为 false。 |
2. 生命周期钩子/事件 (Events) - 在特定时刻执行你的逻辑
| 事件名 (Event) | 参数 (Parameters) | 说明与核心用途 |
|---|---|---|
:on-success |
(response, uploadFile, uploadFiles) |
文件上传成功时触发。response 是服务器返回的数据。 |
:on-error |
(error, uploadFile, uploadFiles) |
文件上传失败（网络层面）时触发。 |
:on-progress |
(event, uploadFile, uploadFiles) |
文件上传过程中触发，可用于自定义进度条。event 包含进度信息。 |
:on-change |
(uploadFile, uploadFiles) |
文件状态改变时（添加、成功、失败、移除）都会触发。 |
:before-upload |
(rawFile) |
上传文件之前的钩子，常用于校验文件大小和格式。如果返回 false 或 rejected Promise，则会中止上传。 |
:on-preview |
(uploadFile) |
点击已上传的文件时触发，常用于实现文件预览（如弹出一个 dialog 显示图片）。 |
:on-remove |
(uploadFile, uploadFiles) |
从内置文件列表移除文件时触发。 |
:before-remove |
(uploadFile, uploadFiles) |
移除文件之前的钩子。可以返回一个 Promise，常用于弹出确认框让用户确认删除。 |
:on-exceed |
(files, uploadFiles) |
当选择的文件数量超出 limit 限制时触发。 |
3. 插槽 (Slots) - 完全自定义组件的显示内容
| 插槽名 (Slot) | 说明 |
|---|---|
#trigger |
自定义触发上传的区域。使用此插槽后，默认的点击或拖拽区域将被替换。 |
#default |
el-upload 组件的主要内容。#trigger 是它的别名。 |
#tip |
自定义提示说明的区域。 |
#file |
作用域插槽，用于完全自定义文件列表的渲染方式。通过 { file } 访问每个文件对象，构建你想要的任何样式。 |
4. 方法 (Methods) - 通过 ref 从外部调用组件内部方法
| 方法名 (Method) | 说明 |
|---|---|
submit() |
当 :auto-upload 为 false 时，手动调用此方法来上传文件列表中的所有文件。 |
abort(file) |
取消某个文件的上传请求。file 是 uploadFile 对象。 |
clearFiles() |
清空已上传的文件列表（但不会触发 :on-remove 钩子）。常用于重置表单。 |