Upload 上传
文件上传控件。提供文件选择、拖拽接收、文件列表、删除四个核心能力。组件不内置 HTTP 上传请求 —— 业务侧通过 update:fileList 拿到文件后自行发请求并回写状态，组件只负责 UI 与状态同步。
基本使用
v-model:fileList 绑定文件列表，点击按钮选择文件。
拖拽上传
drag 把按钮替换成拖拽区，支持点击 / 拖拽两种触发。
照片墙 listType="picture-card"
listType="picture-card" 把列表渲染成网格卡片（104×104），适合相册 / 头像批量上传 / 产品图等场景。有 url 字段时渲染缩略图，否则渲染占位图标；hover 卡片右上角显示删除按钮，点缩略图触发 preview 事件。
多选 + 类型限制
multiple 允许多选；accept 直接传给 native <input>，浏览器会根据 MIME 过滤。
数量与大小限制
max-count限制总数，超出的文件被丢弃 + 触发reject(file, 'maxCount')max-size限制单文件字节数，超出 + 触发reject(file, 'maxSize')before-upload同步过滤函数，返回false拒收 + 触发reject(file, 'beforeUpload')
持续上传中状态
default-status="uploading" 让每个新文件初始为 uploading 状态。业务发完真实请求后，自己改为 done / error。
自定义触发器
default slot 替换默认按钮（拖拽模式下 default slot 不生效）。
自定义列表项
itemRender slot 完全自渲列表，参数 { item, remove }。
禁用
disabled 关掉点击 / 拖拽 / 列表项的 ✕ 按钮。
API
Props
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| fileList | UploadFile[] | -- | 受控文件列表，支持 v-model:fileList |
| defaultFileList | UploadFile[] | [] | 非受控初始列表 |
| accept | string | '' | 接受的文件类型（传给 native input.accept） |
| multiple | boolean | false | 是否允许多选 |
| disabled | boolean | false | 是否禁用 |
| maxCount | number | 0 | 最大文件数；0 表示不限 |
| maxSize | number | 0 | 单文件最大字节数；0 表示不限 |
| beforeUpload | (file: File, fileList: File[]) => boolean | Promise<boolean> | -- | 过滤函数（同步/异步）；返回 false 拒收 |
| drag | boolean | false | 是否渲染拖拽区域代替按钮 |
| showUploadList | boolean | true | 是否渲染文件列表 |
| listType | 'text' | 'picture' | 'picture-card' | 'text' | 列表展示形态；picture 行内显示缩略图；picture-card 网格卡片（104×104） |
| defaultStatus | 'uploading' | 'done' | 'error' | 'done' | 新加文件的初始 status；业务可改为 'uploading' 让组件持续显示加载态 |
| triggerText | string | 点击上传 | 默认按钮文案 |
| dragText | string | 点击或拖拽文件到此区域上传 | 拖拽区文案 |
| removeText | string | 删除 | 列表项 × 按钮的 aria-label |
| customRequest | (options: CustomRequestOptions) => void | -- | 自定义上传函数（onProgress/onSuccess/onError） |
| action | string | '' | 上传地址；未传 customRequest 时用默认 XHR POST |
UploadFile
| 字段 | 类型 | 说明 |
|---|---|---|
| uid | string | 唯一标识；组件生成时自动给 |
| name | string | 文件名 |
| size | number | 字节数 |
| type | string | MIME |
| status | 'uploading' | 'done' | 'error' | 'removed' | 状态 |
| percent | number | 上传进度（0-100） |
| url | string | 已上传的远端 URL（业务回写） |
| response | unknown | 后端响应（业务回写） |
| raw | File | 原始 File 对象 |
Events
| 事件名 | 回调签名 | 触发时机 |
|---|---|---|
| update:fileList | (list: UploadFile[]) | 列表变化 |
| change | (file: UploadFile, list: UploadFile[]) | 单文件添加 / 移除时 |
| remove | (file: UploadFile) | 用户点 × 移除 |
| reject | (file: File, reason: 'maxSize' | 'maxCount' | 'beforeUpload') | 文件被拒收 |
| drop | (e: DragEvent) | 拖拽放下（仅 drag=true） |
| preview | (file: UploadFile) | 点击文件名时触发 |
Slots
| 名称 | 参数 | 说明 |
|---|---|---|
| default | -- | 自定义触发器（drag=true 时不生效） |
| itemRender | { item: UploadFile, remove: () => void } | 自定义单项渲染 |
已知限制（未交付）
- 进度条：
percent字段已支持渲染百分比文字，但没有彩色进度条 UI；后续接入c-progress。 - chunk 分片上传 / 断点续传：复杂场景，留长尾。
- directory 目录选择：input.webkitdirectory 暂未透传。