---
url: /components/upload.md
---
# Upload 上传

文件上传组件：隐藏 input 覆盖触发区，XHR 直传 `action`（FormData 提交，文件字段名由 `name` 指定，`data` 附加表单字段、`headers` 附加请求头），内置文件列表、进度条与数量限制。文件项包含 `uid / name / size / status（ready | uploading | success | fail）/ percentage` 字段；上传过程中 status 为 uploading 并展示进度，结束后按 HTTP 状态码落入 success 或 fail。

## 基础用法

`action` 为必传上传地址，`multiple` 支持一次选择多个文件，`accept` 按扩展名或 MIME 过滤可选文件。

## 受控文件列表

`v-model:file-list` 受控列表，可预置已上传文件（status 为 success 的项带已上传图标），移除文件时同步更新。

## 数量限制

`limit` 限制最大数量，超限不再加入列表并触发 `exceed` 事件。

## 手动上传

`auto-upload=false` 时选择文件仅进入列表（status 为 ready），调用实例方法 `submit` 才开始上传全部 ready 文件。

## 拖拽与照片墙

`drag` 开启拖拽区（点击与拖入都走同一入口，悬停高亮，`#trigger` 可整体替换拖拽区内容，常配 `accept` 限定类型）；`list-type` 三种取值：`text` 普通列表、`picture` 列表项前置文件图标、`picture-card` 触发区与列表呈方形卡片。照片墙常与 `limit` 组合，超限触发 `exceed` 事件且不加入列表。

## 照片墙自定义缩略图

内置列表（含 picture-card）渲染的是「图标 + 文件名」，不含图片缩略图预览，组件也没有缩略图插槽；需要预览时的完整做法：`show-file-list=false` 关闭内置列表，`change` 事件拿到 `file.raw` 后用 FileReader 转 data URL，自行渲染卡片网格（本例 `auto-upload=false` 避免真实上传，仅演示本地预览）。

## 自定义触发区与隐藏列表

`#trigger` 插槽替换默认触发内容（drag 模式下替换整个拖拽区）；`show-file-list=false` 隐藏文件列表，配合上传结果事件自行维护展示。

## API