Upload 上传
完整的文件上传系统，采用新粗野主义设计，支持拖拽上传、文件列表管理、进度追踪和错误处理。
预览
Preview 
基础 text 类型
点击或拖拽文件到此区域上传
document.pdf
1.47 MB
avatar.png
312.5 KB
picture 缩略图列表类型
点击或拖拽文件到此区域上传
sunset.jpg
2.34 MB
picture-card 照片墙类型（最大限制 3 张）
点击或拖拽文件到此区域上传
landscape.jpg
安装
pnpm dlx brutx-vue@latest add upload用法
vue
<script setup>
import { ref } from 'vue'
import { Upload, UploadTrigger, UploadFileList, type UploadFile } from 'brutx-ui-vue'
const fileList = ref<UploadFile[]>([])
async function handleUpload(options) {
// 自定义上传实现
const formData = new FormData()
formData.append('file', options.file)
const response = await fetch('/api/upload', {
method: 'POST',
body: formData,
})
options.onSuccess(response)
}
</script>
<template>
<Upload
v-model:file-list="fileList"
:http-request="handleUpload"
accept="image/*"
:max-size="5 * 1024 * 1024"
>
<template #trigger="{ selectFiles, drag, accept, multiple }">
<UploadTrigger :drag="drag" :accept="accept" :multiple="multiple" @select="selectFiles" />
</template>
<template #file-list="{ files, remove, retry }">
<UploadFileList :files="files" @remove="remove" @retry="retry" />
</template>
</Upload>
</template>图片卡片类型
vue
<script setup>
import { ref } from 'vue'
import { Upload, UploadTrigger, UploadFileList, type UploadFile } from 'brutx-ui-vue'
const fileList = ref<UploadFile[]>([])
</script>
<template>
<Upload
v-model:file-list="fileList"
list-type="picture-card"
:limit="5"
multiple
>
<template #trigger="{ selectFiles, drag, accept, multiple }">
<UploadTrigger :drag="drag" :accept="accept" :multiple="multiple" @select="selectFiles" />
</template>
<template #file-list="{ files, remove }">
<UploadFileList :files="files" list-type="picture-card" @remove="remove" />
</template>
</Upload>
</template>使用钩子函数
vue
<script setup>
import { ref } from 'vue'
import { Upload, UploadTrigger, UploadFileList, type UploadFile } from 'brutx-ui-vue'
const fileList = ref<UploadFile[]>([])
function beforeUpload(file) {
const isImage = file.type.startsWith('image/')
if (!isImage) {
console.error('只能上传图片文件!')
return false
}
return true
}
async function beforeRemove(file) {
return confirm(`确定删除 ${file.name} 吗?`)
}
</script>
<template>
<Upload
v-model:file-list="fileList"
:before-upload="beforeUpload"
:before-remove="beforeRemove"
>
<template #trigger="{ selectFiles, drag, accept, multiple }">
<UploadTrigger :drag="drag" :accept="accept" :multiple="multiple" @select="selectFiles" />
</template>
<template #file-list="{ files, remove }">
<UploadFileList :files="files" @remove="remove" />
</template>
</Upload>
</template>子组件
| 组件 | 说明 |
|---|---|
Upload | 根组件，管理文件列表和上传逻辑 |
UploadTrigger | 触发区域，支持拖拽/点击选择文件 |
UploadFileList | 文件列表容器 |
UploadFileItem | 单个文件项，支持预览、进度和删除 |
API 参考
Upload
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
fileList | UploadFile[] | undefined | []按实例调用工厂函数 | 当前文件列表，支持 v-model:fileList。组件会以 id 同步外部列表，并保留进行中的上传状态。 |
详情声明类型UploadFile[] | undefined 关联类型 UploadFile 类型定义 — UploadFileexport interface UploadFile {
/** 文件唯一标识符 */
id: string
/** 文件名 */
name: string
/** 文件大小（字节） */
size: number
/** 文件 MIME 类型 */
type: string
/** 上传状态 */
status: 'ready' | 'uploading' | 'success' | 'error' | 'canceled'
/** 上传进度，取值范围 0-100 */
progress: number
/** 文件远程访问 URL 或自定义预览地址 */
url?: string
/** 原始 File 对象，用于上传请求、重试及本地预览生成 */
raw?: File
/** 错误信息 */
error?: UploadError
/** 当前已重试次数 */
retryCount?: number
/** 上传中止控制器 */
abortController?: AbortController
}默认值详情
来源packages/ui/src/components/upload/Upload.vue | |||
limit | number | undefined | undefined | 可保留的最大文件数；达到上限时跳过后续文件，并通过 onError 报告限制错误。 |
详情声明类型number | undefined 默认值详情
来源packages/ui/src/components/upload/Upload.vue | |||
multiple | boolean | undefined | true | 是否允许一次选择多个文件；为 false 时，选择器只保留首个文件。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/upload/Upload.vue | |||
accept | string | undefined | undefined | 传给原生文件选择器的文件类型提示，并用于校验所选文件。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/upload/Upload.vue | |||
maxSize | number | undefined | undefined | 单个文件的最大大小，单位为字节；超出时跳过该文件并调用 onError。 |
详情声明类型number | undefined 默认值详情
来源packages/ui/src/components/upload/Upload.vue | |||
maxRetries | number | undefined | 3 | 单个文件允许重试上传的次数；达到上限后，重试调用会报告错误并停止上传。 |
详情声明类型number | undefined 默认值详情
来源packages/ui/src/components/upload/Upload.vue | |||
beforeUpload | ((file: File) => boolean | Promise<boolean>) | undefined | undefined | 在文件加入列表前运行的同步或异步校验；返回 false 时跳过该文件。 |
详情声明类型((file: File) => boolean | Promise<boolean>) | undefined 默认值详情
来源packages/ui/src/components/upload/Upload.vue | |||
beforeRemove | ((file: UploadFile) => boolean | Promise<boolean>) | undefined | undefined | 删除文件前运行的同步或异步确认；返回 false 时保留该文件。 |
详情声明类型((file: UploadFile) => boolean | Promise<boolean>) | undefined 关联类型 UploadFile 类型定义 — UploadFileexport interface UploadFile {
/** 文件唯一标识符 */
id: string
/** 文件名 */
name: string
/** 文件大小（字节） */
size: number
/** 文件 MIME 类型 */
type: string
/** 上传状态 */
status: 'ready' | 'uploading' | 'success' | 'error' | 'canceled'
/** 上传进度，取值范围 0-100 */
progress: number
/** 文件远程访问 URL 或自定义预览地址 */
url?: string
/** 原始 File 对象，用于上传请求、重试及本地预览生成 */
raw?: File
/** 错误信息 */
error?: UploadError
/** 当前已重试次数 */
retryCount?: number
/** 上传中止控制器 */
abortController?: AbortController
}默认值详情
来源packages/ui/src/components/upload/Upload.vue | |||
httpRequest | ((options: UploadRequestOptions) => Promise<void>) | undefined | undefined | 负责实际上传的异步实现；接收文件、取消信号、进度回调和完成/错误回调。未提供时文件仍可加入列表，但不会启动网络上传。 |
详情声明类型((options: UploadRequestOptions) => Promise<void>) | undefined 关联类型 UploadRequestOptions 类型定义 — UploadRequestOptionsexport interface UploadRequestOptions {
/** 待上传的文件 */
file: File
/** 中止信号 */
signal: AbortSignal
/** 进度回调函数，percent 取值范围 0-100 */
onProgress: (percent: number) => void
/** 成功回调函数 */
onSuccess: (response: unknown) => void
/** 失败回调函数 */
onError: (error: UploadError) => void
}默认值详情
来源packages/ui/src/components/upload/Upload.vue | |||
listType | "text" | "picture" | "picture-card" | undefined | "text" | 选择文件列表的文本、图片或图片卡片布局。 |
详情声明类型"text" | "picture" | "picture-card" | undefined 字面量
默认值详情
来源packages/ui/src/components/upload/Upload.vue | |||
autoUpload | boolean | undefined | true | 是否在文件通过校验并加入列表后立即启动上传；关闭后可通过 retryUpload 主动启动上传。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/upload/Upload.vue | |||
drag | boolean | undefined | true | 是否启用触发区域的拖放选择行为。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/upload/Upload.vue | |||
onError | ((error: UploadError, file: UploadFile) => void) | undefined | undefined | 收到文件类型/大小/数量校验错误、上传失败或重试次数超限时调用的回调。 |
详情声明类型((error: UploadError, file: UploadFile) => void) | undefined 关联类型 UploadError 类型定义 — UploadErrorexport interface UploadError {
/** 错误消息 */
message: string
/** 错误代码 */
code?: string
/** HTTP 状态码 */
status?: number
}UploadFile 类型定义 — UploadFileexport interface UploadFile {
/** 文件唯一标识符 */
id: string
/** 文件名 */
name: string
/** 文件大小（字节） */
size: number
/** 文件 MIME 类型 */
type: string
/** 上传状态 */
status: 'ready' | 'uploading' | 'success' | 'error' | 'canceled'
/** 上传进度，取值范围 0-100 */
progress: number
/** 文件远程访问 URL 或自定义预览地址 */
url?: string
/** 原始 File 对象，用于上传请求、重试及本地预览生成 */
raw?: File
/** 错误信息 */
error?: UploadError
/** 当前已重试次数 */
retryCount?: number
/** 上传中止控制器 */
abortController?: AbortController
}默认值详情
来源packages/ui/src/components/upload/Upload.vue | |||
class | string | undefined | undefined | 追加到 Upload 根容器的自定义 CSS 类。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/upload/Upload.vue | |||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
@update:fileList | [files: UploadFile[]] | 文件加入或移除后发出新的文件列表副本，用于同步 v-model:fileList。 |
详情声明类型[files: UploadFile[]] 关联类型 UploadFile 类型定义 — UploadFileexport interface UploadFile {
/** 文件唯一标识符 */
id: string
/** 文件名 */
name: string
/** 文件大小（字节） */
size: number
/** 文件 MIME 类型 */
type: string
/** 上传状态 */
status: 'ready' | 'uploading' | 'success' | 'error' | 'canceled'
/** 上传进度，取值范围 0-100 */
progress: number
/** 文件远程访问 URL 或自定义预览地址 */
url?: string
/** 原始 File 对象，用于上传请求、重试及本地预览生成 */
raw?: File
/** 错误信息 */
error?: UploadError
/** 当前已重试次数 */
retryCount?: number
/** 上传中止控制器 */
abortController?: AbortController
}来源packages/ui/src/components/upload/Upload.vue | ||
@file-change | [file: UploadFile] | 文件通过校验、加入内部列表后发出；此时状态为 ready，即使 autoUpload 为 true 也早于上传完成。 |
详情声明类型[file: UploadFile] 关联类型 UploadFile 类型定义 — UploadFileexport interface UploadFile {
/** 文件唯一标识符 */
id: string
/** 文件名 */
name: string
/** 文件大小（字节） */
size: number
/** 文件 MIME 类型 */
type: string
/** 上传状态 */
status: 'ready' | 'uploading' | 'success' | 'error' | 'canceled'
/** 上传进度，取值范围 0-100 */
progress: number
/** 文件远程访问 URL 或自定义预览地址 */
url?: string
/** 原始 File 对象，用于上传请求、重试及本地预览生成 */
raw?: File
/** 错误信息 */
error?: UploadError
/** 当前已重试次数 */
retryCount?: number
/** 上传中止控制器 */
abortController?: AbortController
}来源packages/ui/src/components/upload/Upload.vue | ||
@file-remove | [file: UploadFile] | beforeRemove 未拒绝且文件确实存在于列表中、移除完成后发出。 |
详情声明类型[file: UploadFile] 关联类型 UploadFile 类型定义 — UploadFileexport interface UploadFile {
/** 文件唯一标识符 */
id: string
/** 文件名 */
name: string
/** 文件大小（字节） */
size: number
/** 文件 MIME 类型 */
type: string
/** 上传状态 */
status: 'ready' | 'uploading' | 'success' | 'error' | 'canceled'
/** 上传进度，取值范围 0-100 */
progress: number
/** 文件远程访问 URL 或自定义预览地址 */
url?: string
/** 原始 File 对象，用于上传请求、重试及本地预览生成 */
raw?: File
/** 错误信息 */
error?: UploadError
/** 当前已重试次数 */
retryCount?: number
/** 上传中止控制器 */
abortController?: AbortController
}来源packages/ui/src/components/upload/Upload.vue | ||
@file-success | [file: UploadFile] | 自定义上传实现调用 onSuccess 后发出；已取消的上传不会产生此事件。 |
详情声明类型[file: UploadFile] 关联类型 UploadFile 类型定义 — UploadFileexport interface UploadFile {
/** 文件唯一标识符 */
id: string
/** 文件名 */
name: string
/** 文件大小（字节） */
size: number
/** 文件 MIME 类型 */
type: string
/** 上传状态 */
status: 'ready' | 'uploading' | 'success' | 'error' | 'canceled'
/** 上传进度，取值范围 0-100 */
progress: number
/** 文件远程访问 URL 或自定义预览地址 */
url?: string
/** 原始 File 对象，用于上传请求、重试及本地预览生成 */
raw?: File
/** 错误信息 */
error?: UploadError
/** 当前已重试次数 */
retryCount?: number
/** 上传中止控制器 */
abortController?: AbortController
}来源packages/ui/src/components/upload/Upload.vue | ||
@file-error | [file: UploadFile, error: UploadError] | 上传实现报告失败、上传 Promise 拒绝或重试次数超限时发出；仅校验失败会调用 onError，不会发出此事件。 |
详情声明类型[file: UploadFile, error: UploadError] 关联类型 UploadError 类型定义 — UploadErrorexport interface UploadError {
/** 错误消息 */
message: string
/** 错误代码 */
code?: string
/** HTTP 状态码 */
status?: number
}UploadFile 类型定义 — UploadFileexport interface UploadFile {
/** 文件唯一标识符 */
id: string
/** 文件名 */
name: string
/** 文件大小（字节） */
size: number
/** 文件 MIME 类型 */
type: string
/** 上传状态 */
status: 'ready' | 'uploading' | 'success' | 'error' | 'canceled'
/** 上传进度，取值范围 0-100 */
progress: number
/** 文件远程访问 URL 或自定义预览地址 */
url?: string
/** 原始 File 对象，用于上传请求、重试及本地预览生成 */
raw?: File
/** 错误信息 */
error?: UploadError
/** 当前已重试次数 */
retryCount?: number
/** 上传中止控制器 */
abortController?: AbortController
}来源packages/ui/src/components/upload/Upload.vue | ||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
#trigger | { selectFiles: (files: FileList | File[]) => Promise<void>; limit: number | undefined; multiple: boolean; accept: string | undefined; drag: boolean; } | 替换文件选择触发区域；作用域提供 selectFiles、limit、multiple、accept 和 drag，供自定义控件选择文件或呈现配置。 |
详情声明类型{ selectFiles: (files: FileList | File[]) => Promise<void>; limit: number | undefined; multiple: boolean; accept: string | undefined; drag: boolean; }来源packages/ui/src/components/upload/Upload.vue | ||
#file-list | { files: { id: string; name: string; size: number; type: string; status: "success" | "error" | "ready" | "uploading" | "canceled"; progress: number; url?: string | undefined; raw?: { readonly lastModified: number; readonly name: string; readonly webkitRelativePath: string; readonly size: number; readonly type: string; arrayBuffer: () => Promise<ArrayBuffer>; bytes: () => Promise<Uint8Array<ArrayBuffer>>; slice: (start?: number | undefined, end?: number | undefined, contentType?: string | undefined) => Blob; stream: () => ReadableStream<Uint8Array<ArrayBuffer>>; text: () => Promise<string>; } | undefined; error?: { message: string; code?: string | undefined; status?: number | undefined; } | undefined; retryCount?: number | undefined; abortController?: { readonly signal: { readonly aborted: boolean; onabort: ((this: AbortSignal, ev: Event) => any) | null; readonly reason: any; throwIfAborted: () => void; addEventListener: { <K extends keyof AbortSignalEventMap>(type: K, listener: (this: AbortSignal, ev: AbortSignalEventMap[K]) => any, options?: boolean | AddEventListenerOptions | undefined): void; (type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions | undefined): void; }; removeEventListener: { <K extends keyof AbortSignalEventMap>(type: K, listener: (this: AbortSignal, ev: AbortSignalEventMap[K]) => any, options?: boolean | EventListenerOptions | undefined): void; (type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions | undefined): void; }; dispatchEvent: (event: Event) => boolean; }; abort: (reason?: any) => void; } | undefined; }[]; listType: "text" | "picture" | "picture-card"; remove: (file: UploadFile) => Promise<void>; retry: (file: UploadFile) => Promise<void>; } | 替换文件列表；作用域提供当前 files、listType 以及 remove(file) 和 retry(file) 操作。 |
详情声明类型{ files: { id: string; name: string; size: number; type: string; status: "success" | "error" | "ready" | "uploading" | "canceled"; progress: number; url?: string | undefined; raw?: { readonly lastModified: number; readonly name: string; readonly webkitRelativePath: string; readonly size: number; readonly type: string; arrayBuffer: () => Promise<ArrayBuffer>; bytes: () => Promise<Uint8Array<ArrayBuffer>>; slice: (start?: number | undefined, end?: number | undefined, contentType?: string | undefined) => Blob; stream: () => ReadableStream<Uint8Array<ArrayBuffer>>; text: () => Promise<string>; } | undefined; error?: { message: string; code?: string | undefined; status?: number | undefined; } | undefined; retryCount?: number | undefined; abortController?: { readonly signal: { readonly aborted: boolean; onabort: ((this: AbortSignal, ev: Event) => any) | null; readonly reason: any; throwIfAborted: () => void; addEventListener: { <K extends keyof AbortSignalEventMap>(type: K, listener: (this: AbortSignal, ev: AbortSignalEventMap[K]) => any, options?: boolean | AddEventListenerOptions | undefined): void; (type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions | undefined): void; }; removeEventListener: { <K extends keyof AbortSignalEventMap>(type: K, listener: (this: AbortSignal, ev: AbortSignalEventMap[K]) => any, options?: boolean | EventListenerOptions | undefined): void; (type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions | undefined): void; }; dispatchEvent: (event: Event) => boolean; }; abort: (reason?: any) => void; } | undefined; }[]; listType: "text" | "picture" | "picture-card"; remove: (file: UploadFile) => Promise<void>; retry: (file: UploadFile) => Promise<void>; }关联类型 UploadFile 类型定义 — UploadFileexport interface UploadFile {
/** 文件唯一标识符 */
id: string
/** 文件名 */
name: string
/** 文件大小（字节） */
size: number
/** 文件 MIME 类型 */
type: string
/** 上传状态 */
status: 'ready' | 'uploading' | 'success' | 'error' | 'canceled'
/** 上传进度，取值范围 0-100 */
progress: number
/** 文件远程访问 URL 或自定义预览地址 */
url?: string
/** 原始 File 对象，用于上传请求、重试及本地预览生成 */
raw?: File
/** 错误信息 */
error?: UploadError
/** 当前已重试次数 */
retryCount?: number
/** 上传中止控制器 */
abortController?: AbortController
}来源packages/ui/src/components/upload/Upload.vue | ||
#default | {} | 在触发区域和文件列表之后渲染的附加内容，不接收作用域参数。 |
详情声明类型{}来源packages/ui/src/components/upload/Upload.vue | ||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
handleFileSelect | (files: FileList | File[]) => Promise<void> | 以编程方式提交 FileList 或 File 数组；执行相同的文件校验、beforeUpload、列表更新及可选自动上传流程。 |
详情声明类型(files: FileList | File[]) => Promise<void> 来源packages/ui/src/components/upload/Upload.vue | ||
handleFileRemove | (file: UploadFile) => Promise<void> | 以编程方式移除指定文件；仍会遵循 beforeRemove 并中止进行中的上传。 |
详情声明类型(file: UploadFile) => Promise<void> 关联类型 UploadFile 类型定义 — UploadFileexport interface UploadFile {
/** 文件唯一标识符 */
id: string
/** 文件名 */
name: string
/** 文件大小（字节） */
size: number
/** 文件 MIME 类型 */
type: string
/** 上传状态 */
status: 'ready' | 'uploading' | 'success' | 'error' | 'canceled'
/** 上传进度，取值范围 0-100 */
progress: number
/** 文件远程访问 URL 或自定义预览地址 */
url?: string
/** 原始 File 对象，用于上传请求、重试及本地预览生成 */
raw?: File
/** 错误信息 */
error?: UploadError
/** 当前已重试次数 */
retryCount?: number
/** 上传中止控制器 */
abortController?: AbortController
}来源packages/ui/src/components/upload/Upload.vue | ||
retryUpload | (file: UploadFile) => Promise<void> | 以编程方式重试指定文件；成功文件不重试，且受 maxRetries 限制。 |
详情声明类型(file: UploadFile) => Promise<void> 关联类型 UploadFile 类型定义 — UploadFileexport interface UploadFile {
/** 文件唯一标识符 */
id: string
/** 文件名 */
name: string
/** 文件大小（字节） */
size: number
/** 文件 MIME 类型 */
type: string
/** 上传状态 */
status: 'ready' | 'uploading' | 'success' | 'error' | 'canceled'
/** 上传进度，取值范围 0-100 */
progress: number
/** 文件远程访问 URL 或自定义预览地址 */
url?: string
/** 原始 File 对象，用于上传请求、重试及本地预览生成 */
raw?: File
/** 错误信息 */
error?: UploadError
/** 当前已重试次数 */
retryCount?: number
/** 上传中止控制器 */
abortController?: AbortController
}来源packages/ui/src/components/upload/Upload.vue | ||
UploadFileItem
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
file必填 | UploadFile | — | 要呈现的文件及其上传状态、进度和错误信息。 |
详情声明类型UploadFile 关联类型 UploadFile 类型定义 — UploadFileexport interface UploadFile {
/** 文件唯一标识符 */
id: string
/** 文件名 */
name: string
/** 文件大小（字节） */
size: number
/** 文件 MIME 类型 */
type: string
/** 上传状态 */
status: 'ready' | 'uploading' | 'success' | 'error' | 'canceled'
/** 上传进度，取值范围 0-100 */
progress: number
/** 文件远程访问 URL 或自定义预览地址 */
url?: string
/** 原始 File 对象，用于上传请求、重试及本地预览生成 */
raw?: File
/** 错误信息 */
error?: UploadError
/** 当前已重试次数 */
retryCount?: number
/** 上传中止控制器 */
abortController?: AbortController
}默认值详情
来源packages/ui/src/components/upload/UploadFileItem.vue | |||
listType | "text" | "picture" | "picture-card" | undefined | "text" | 选择单个文件项的文本、图片或图片卡片布局。 |
详情声明类型"text" | "picture" | "picture-card" | undefined 字面量
默认值详情
来源packages/ui/src/components/upload/UploadFileItem.vue | |||
class | string | undefined | undefined | 追加到文件项根元素的自定义 CSS 类。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/upload/UploadFileItem.vue | |||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
@remove | [] | 用户激活删除按钮时发出，不携带参数；上传逻辑由父级处理。 |
详情声明类型[] 来源packages/ui/src/components/upload/UploadFileItem.vue | ||
@retry | [] | 仅当文件状态为 error 且用户激活重试按钮时发出，不携带参数。 |
详情声明类型[] 来源packages/ui/src/components/upload/UploadFileItem.vue | ||
UploadFileList
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
files必填 | UploadFile[] | — | 要渲染的文件项列表；列表为空时不渲染容器。 |
详情声明类型UploadFile[] 关联类型 UploadFile 类型定义 — UploadFileexport interface UploadFile {
/** 文件唯一标识符 */
id: string
/** 文件名 */
name: string
/** 文件大小（字节） */
size: number
/** 文件 MIME 类型 */
type: string
/** 上传状态 */
status: 'ready' | 'uploading' | 'success' | 'error' | 'canceled'
/** 上传进度，取值范围 0-100 */
progress: number
/** 文件远程访问 URL 或自定义预览地址 */
url?: string
/** 原始 File 对象，用于上传请求、重试及本地预览生成 */
raw?: File
/** 错误信息 */
error?: UploadError
/** 当前已重试次数 */
retryCount?: number
/** 上传中止控制器 */
abortController?: AbortController
}默认值详情
来源packages/ui/src/components/upload/UploadFileList.vue | |||
listType | "text" | "picture" | "picture-card" | undefined | "text" | 应用于各文件项的文本、图片或图片卡片布局。 |
详情声明类型"text" | "picture" | "picture-card" | undefined 字面量
默认值详情
来源packages/ui/src/components/upload/UploadFileList.vue | |||
class | string | undefined | undefined | 追加到文件列表容器的自定义 CSS 类。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/upload/UploadFileList.vue | |||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
@remove | [file: UploadFile] | 子项发出 remove 时转发对应 UploadFile。 |
详情声明类型[file: UploadFile] 关联类型 UploadFile 类型定义 — UploadFileexport interface UploadFile {
/** 文件唯一标识符 */
id: string
/** 文件名 */
name: string
/** 文件大小（字节） */
size: number
/** 文件 MIME 类型 */
type: string
/** 上传状态 */
status: 'ready' | 'uploading' | 'success' | 'error' | 'canceled'
/** 上传进度，取值范围 0-100 */
progress: number
/** 文件远程访问 URL 或自定义预览地址 */
url?: string
/** 原始 File 对象，用于上传请求、重试及本地预览生成 */
raw?: File
/** 错误信息 */
error?: UploadError
/** 当前已重试次数 */
retryCount?: number
/** 上传中止控制器 */
abortController?: AbortController
}来源packages/ui/src/components/upload/UploadFileList.vue | ||
@retry | [file: UploadFile] | 子项发出 retry 时转发对应 UploadFile。 |
详情声明类型[file: UploadFile] 关联类型 UploadFile 类型定义 — UploadFileexport interface UploadFile {
/** 文件唯一标识符 */
id: string
/** 文件名 */
name: string
/** 文件大小（字节） */
size: number
/** 文件 MIME 类型 */
type: string
/** 上传状态 */
status: 'ready' | 'uploading' | 'success' | 'error' | 'canceled'
/** 上传进度，取值范围 0-100 */
progress: number
/** 文件远程访问 URL 或自定义预览地址 */
url?: string
/** 原始 File 对象，用于上传请求、重试及本地预览生成 */
raw?: File
/** 错误信息 */
error?: UploadError
/** 当前已重试次数 */
retryCount?: number
/** 上传中止控制器 */
abortController?: AbortController
}来源packages/ui/src/components/upload/UploadFileList.vue | ||
UploadTrigger
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
drag | boolean | undefined | true | 是否处理拖放文件事件；禁用拖放时不接受拖放并清除拖动态。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/upload/UploadTrigger.vue | |||
disabled | boolean | undefined | false | 禁用文件选择和拖放，并从键盘焦点顺序中移除触发区域。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/upload/UploadTrigger.vue | |||
accept | string | undefined | undefined | 传给隐藏原生文件输入的 accept 文件类型提示。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/upload/UploadTrigger.vue | |||
multiple | boolean | undefined | true | 传给原生文件输入的多选设置；为 false 时浏览选择或拖放都只保留首个文件。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/upload/UploadTrigger.vue | |||
class | string | undefined | undefined | 追加到可聚焦触发区域的自定义 CSS 类。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/upload/UploadTrigger.vue | |||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
@select | [files: File[], source: "browse" | "drop"] | 通过浏览选择或拖放得到非空文件数组时发出，并附带 browse 或 drop 来源；multiple 为 false 时数组最多包含一个文件。 |
详情声明类型[files: File[], source: "browse" | "drop"] 字面量
来源packages/ui/src/components/upload/UploadTrigger.vue | ||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
#default | { isDragging: boolean; triggerFileInput: () => void; } | 替换整个触发区域；作用域提供实时 isDragging 状态及可编程打开文件选择器的 triggerFileInput()。 |
详情声明类型{ isDragging: boolean; triggerFileInput: () => void; }来源packages/ui/src/components/upload/UploadTrigger.vue | ||
#text | {} | 替换默认触发区域的主要提示文本；未提供 default 插槽时显示。若未提供此插槽，源码当前使用固定中文提示“点击或拖拽文件到此区域上传”。 |
详情声明类型{}来源packages/ui/src/components/upload/UploadTrigger.vue | ||
#hint | {} | 替换主要提示下方的辅助说明；未提供时该区域为空。 |
详情声明类型{}来源packages/ui/src/components/upload/UploadTrigger.vue | ||
类型定义
UploadFile
typescript
interface UploadFile {
id: string
name: string
size: number
type: string
status: 'ready' | 'uploading' | 'success' | 'error' | 'canceled'
progress: number
url?: string
raw?: File
error?: UploadError
retryCount?: number
abortController?: AbortController
}UploadError
typescript
interface UploadError {
message: string
code?: string
status?: number
}UploadRequestOptions
typescript
interface UploadRequestOptions {
file: File
signal: AbortSignal
onProgress: (percent: number) => void
onSuccess: (response: unknown) => void
onError: (error: UploadError) => void
}可访问性
- 键盘操作：触发区域可通过
Enter/Space键激活 - ARIA 属性：隐藏的文件输入框有正确的标签
- 屏幕阅读器：文件状态和进度会被播报