Appearance
Upload 上传
用于文件与图片上传，支持数量限制、多选、类型限制、列表展示、拖拽和图片裁剪。
示例
基础用法
文件列表
list-type="file-list" 用于通用文件上传，展示文件名称列表。
图片宫格
list-type="image-grid" 用于多图上传，以宫格形式展示图片预览。
单图上传
list-type="image-only" 用于单图/头像上传，只展示一张图片，始终只保留一张。
图片裁剪
auto-cropper 控制是否开启图片裁剪，仅在 list-type="image-grid" 或 list-type="image-only" 且上传图片时生效。
全屏拖拽
is-full-screen-drag 开启全屏拖拽，用户可以将文件拖入页面任意区域上传。
自定义插槽
通过 trigger 插槽自定义触发内容，通过 tip 插槽自定义图片类型上传提示。
自定义上传前校验
通过 before-upload 可以在上传前做自定义校验，返回 false 或 Promise.reject 会阻止上传。
API
Props
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| model-value | 上传文件列表 | UploadFile[] | [] |
| limit | 最大上传数量 | number | 9 |
| multiple | 是否多选 | boolean | true |
| suffixes | 允许的文件后缀 | FileSuffix[] | Object.values(FileSuffixEnum) |
| disabled | 是否禁用 | boolean | false |
| scene-id | 上传场景 | '0' | '1' | '1' |
| list-type | 列表类型 | 'file-list' | 'image-grid' | 'image-only' | 'file-list' |
| show-trigger | 是否显示上传触发器 | boolean | true |
| show-list | 是否显示文件列表 | boolean | false |
| is-full-screen-drag | 是否开启全屏拖拽 | boolean | false |
| size-type | 预设大小类型 | keyof fileSizeLimitConfigMap | 'normal' |
| size | 自定义大小限制 | number | 0 |
| auto-cropper | 是否开启图片裁剪 | boolean | true |
| copper-options | 图片裁剪配置 | CopperOptions | {} |
| before-upload | 上传前回调 | (rawFile: UploadRawFile) => Promise<boolean> | Promise.resolve(true) |
Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| update:model-value | 文件列表变化时触发 | (files: UploadFile[]) |
| success | 上传成功时触发 | ({ response, uploadFile, uploadFiles }) |
| error | 上传失败时触发 | ({ error, uploadFile, uploadFiles }) |
| change | 文件状态变化时触发 | ({ uploadFile, uploadFiles }) |
Slots
| 插槽名 | 说明 | 作用域参数 |
|---|---|---|
| trigger | 自定义上传触发内容 | - |
| tip | 自定义图片网格和单图触发器中的提示内容 | - |
Exposes
| 方法名 | 说明 | 类型 |
|---|---|---|
| abort | 中断指定文件上传 | (uploadFile: UploadFile) => void |
| remove | 移除指定文件并中断上传 | (uploadFile: UploadFile) => void |
| choose | 主动打开文件选择器 | () => void |
| format | 将地址或文件对象格式化列表 | (data: string[] | { url: string }[] | UploadFile[]) => UploadFile[] |
| validate | 校验文件列表是否满足要求 | (isRequired?: boolean) => boolean |
内部布局导出
| 导出名 | 说明 | 所属场景 |
|---|---|---|
| MtUploadFileListLayout | 文件列表展示布局 | list-type="file-list" |
| MtUploadImageGridLayout | 多图宫格展示布局，包含预览、裁剪和移除入口 | list-type="image-grid" |
| MtUploadImageOnlyLayout | 单图展示布局，包含预览、裁剪和移除入口 | list-type="image-only" |
这些布局组件随 Upload 一同导出，正常业务优先通过 Upload 的 list-type 切换使用，不建议在组件导航中作为独立组件入口。
注意事项
- 上传前应通过
ConfigProvider注入file-upload配置，至少提供getToken。 - 示例中的
getToken仅用于示例结构，真实项目应由业务安全地获取上传鉴权 token。 before-upload返回false或 reject 时会阻止当前文件上传，建议按类型返回Promise<boolean>。- 建议结合
before-upload校验文件大小、类型和业务权限。