BrutxUI

English

简体中文

English

简体中文

Appearance

Upload ​

A complete file upload system built with Neo-Brutalism design, featuring drag-and-drop, file list management, progress tracking, and error handling.

Preview ​

Preview

基础 text 类型

点击或拖拽文件到此区域上传

document.pdf

1.47 MB

avatar.png

312.5 KB

picture 缩略图列表类型

点击或拖拽文件到此区域上传

sunset.jpg

sunset.jpg

2.34 MB

picture-card 照片墙类型（最大限制 3 张）

点击或拖拽文件到此区域上传

landscape.jpg

landscape.jpg

Installation ​

pnpm dlx brutx-vue@latest add upload

Usage ​

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) {
    // Custom upload implementation
    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>

Picture Card Type ​

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>

With Hooks ​

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>

Sub-components ​

ComponentDescription
UploadRoot component, manages file list and upload logic
UploadTriggerTrigger area for file selection (drag/click)
UploadFileListFile list container
UploadFileItemSingle file item with preview, progress, and delete

API Reference ​

Upload

Upload — Props
NameTypeDefaultDescription
fileList
UploadFile[] | undefined
[]

Factory evaluated per instance

The current file list, available through v-model:fileList. The component syncs external entries by id and preserves in-progress upload state.
Details

Declared type

UploadFile[] | undefined

Referenced types

UploadFile
Type definition — UploadFile
export 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
}

Default value details

Declaration
() => []

Source: packages/ui/src/components/upload/Upload.vue

Resolved value
[]

Source

Upload.vue:9

packages/ui/src/components/upload/Upload.vue

limit
number | undefined
undefined
Maximum number of files. Once reached, additional files are skipped and the limit error is reported through onError.
Details

Declared type

number | undefined

Default value details

Declaration
undefined

Source: packages/ui/src/components/upload/Upload.vue

Resolved value
undefined

Source

Upload.vue:11

packages/ui/src/components/upload/Upload.vue

multiple
boolean | undefined
true
Whether to allow selecting multiple files at once. When false, the picker keeps only the first file.
Details

Declared type

boolean | undefined

Literal values

  • false
  • true

Default value details

Declaration
true

Source: packages/ui/src/components/upload/Upload.vue

Resolved value
true

Source

Upload.vue:13

packages/ui/src/components/upload/Upload.vue

accept
string | undefined
undefined
The accepted file type hint passed to the native picker and used to validate selected files.
Details

Declared type

string | undefined

Default value details

Declaration
undefined

Source: packages/ui/src/components/upload/Upload.vue

Resolved value
undefined

Source

Upload.vue:15

packages/ui/src/components/upload/Upload.vue

maxSize
number | undefined
undefined
Maximum size of one file in bytes. Oversized files are skipped and reported through onError.
Details

Declared type

number | undefined

Default value details

Declaration
undefined

Source: packages/ui/src/components/upload/Upload.vue

Resolved value
undefined

Source

Upload.vue:17

packages/ui/src/components/upload/Upload.vue

maxRetries
number | undefined
3
Maximum retry attempts per file. Once reached, another retry reports an error and does not start an upload.
Details

Declared type

number | undefined

Default value details

Declaration
3

Source: packages/ui/src/components/upload/Upload.vue

Resolved value
3

Source

Upload.vue:19

packages/ui/src/components/upload/Upload.vue

beforeUpload
((file: File) => boolean | Promise<boolean>) | undefined
undefined
A synchronous or asynchronous check run before a file is added to the list. Returning false skips that file.
Details

Declared type

((file: File) => boolean | Promise<boolean>) | undefined

Default value details

Declaration
undefined

Source: packages/ui/src/components/upload/Upload.vue

Resolved value
undefined

Source

Upload.vue:21

packages/ui/src/components/upload/Upload.vue

beforeRemove
((file: UploadFile) => boolean | Promise<boolean>) | undefined
undefined
A synchronous or asynchronous confirmation run before removal. Returning false keeps the file in the list.
Details

Declared type

((file: UploadFile) => boolean | Promise<boolean>) | undefined

Referenced types

UploadFile
Type definition — UploadFile
export 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
}

Default value details

Declaration
undefined

Source: packages/ui/src/components/upload/Upload.vue

Resolved value
undefined

Source

Upload.vue:23

packages/ui/src/components/upload/Upload.vue

httpRequest
((options: UploadRequestOptions) => Promise<void>) | undefined
undefined
The asynchronous upload implementation. It receives the file, abort signal, progress callback, and success/error callbacks. Without it, files can still be added to the list but no upload starts.
Details

Declared type

((options: UploadRequestOptions) => Promise<void>) | undefined

Referenced types

UploadRequestOptions
Type definition — UploadRequestOptions
export interface UploadRequestOptions {
    /** 待上传的文件 */
    file: File
    /** 中止信号 */
    signal: AbortSignal
    /** 进度回调函数，percent 取值范围 0-100 */
    onProgress: (percent: number) => void
    /** 成功回调函数 */
    onSuccess: (response: unknown) => void
    /** 失败回调函数 */
    onError: (error: UploadError) => void
}

Default value details

Declaration
undefined

Source: packages/ui/src/components/upload/Upload.vue

Resolved value
undefined

Source

Upload.vue:25

packages/ui/src/components/upload/Upload.vue

listType
"text" | "picture" | "picture-card" | undefined
"text"
Selects the text, picture, or picture-card layout for file entries.
Details

Declared type

"text" | "picture" | "picture-card" | undefined

Literal values

  • "picture-card"
  • "picture"
  • "text"

Default value details

Declaration
'text'

Source: packages/ui/src/components/upload/Upload.vue

Resolved value
"text"

Source

Upload.vue:27

packages/ui/src/components/upload/Upload.vue

autoUpload
boolean | undefined
true
Whether to start uploading as soon as a validated file is added. When false, retryUpload can start the upload explicitly.
Details

Declared type

boolean | undefined

Literal values

  • false
  • true

Default value details

Declaration
true

Source: packages/ui/src/components/upload/Upload.vue

Resolved value
true

Source

Upload.vue:29

packages/ui/src/components/upload/Upload.vue

drag
boolean | undefined
true
Enables or disables file dropping on the trigger area.
Details

Declared type

boolean | undefined

Literal values

  • false
  • true

Default value details

Declaration
true

Source: packages/ui/src/components/upload/Upload.vue

Resolved value
true

Source

Upload.vue:31

packages/ui/src/components/upload/Upload.vue

onError
((error: UploadError, file: UploadFile) => void) | undefined
undefined
Called for file type, size, or count validation failures, upload failures, and retry-limit errors.
Details

Declared type

((error: UploadError, file: UploadFile) => void) | undefined

Referenced types

UploadError
Type definition — UploadError
export interface UploadError {
    /** 错误消息 */
    message: string
    /** 错误代码 */
    code?: string
    /** HTTP 状态码 */
    status?: number
}
UploadFile
Type definition — UploadFile
export 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
}

Default value details

Declaration
undefined

Source: packages/ui/src/components/upload/Upload.vue

Resolved value
undefined

Source

Upload.vue:33

packages/ui/src/components/upload/Upload.vue

class
string | undefined
undefined
Custom CSS classes added to the Upload root container.
Details

Declared type

string | undefined

Default value details

Declaration
undefined

Source: packages/ui/src/components/upload/Upload.vue

Resolved value
undefined

Source

Upload.vue:34

packages/ui/src/components/upload/Upload.vue

Upload — Events
NameSignature or typeDescription
@update:fileList
[files: UploadFile[]]
Emits a copy of the file list after a file is added or removed to update v-model:fileList.
Details

Declared type

[files: UploadFile[]]

Referenced types

UploadFile
Type definition — UploadFile
export 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
}

Source

Upload.vue

packages/ui/src/components/upload/Upload.vue

@file-change
[file: UploadFile]
Emitted after a validated file is added to the internal list. Its status is ready, and this occurs before upload completion even when autoUpload is true.
Details

Declared type

[file: UploadFile]

Referenced types

UploadFile
Type definition — UploadFile
export 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
}

Source

Upload.vue

packages/ui/src/components/upload/Upload.vue

@file-remove
[file: UploadFile]
Emitted after removal completes, provided beforeRemove did not reject it and the file was present in the list.
Details

Declared type

[file: UploadFile]

Referenced types

UploadFile
Type definition — UploadFile
export 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
}

Source

Upload.vue

packages/ui/src/components/upload/Upload.vue

@file-success
[file: UploadFile]
Emitted when the custom upload implementation calls onSuccess. Canceled uploads do not emit this event.
Details

Declared type

[file: UploadFile]

Referenced types

UploadFile
Type definition — UploadFile
export 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
}

Source

Upload.vue

packages/ui/src/components/upload/Upload.vue

@file-error
[file: UploadFile, error: UploadError]
Emitted when the upload callback reports an error, the upload Promise rejects, or retries are exhausted. Validation failures call onError without emitting this event.
Details

Declared type

[file: UploadFile, error: UploadError]

Referenced types

UploadError
Type definition — UploadError
export interface UploadError {
    /** 错误消息 */
    message: string
    /** 错误代码 */
    code?: string
    /** HTTP 状态码 */
    status?: number
}
UploadFile
Type definition — UploadFile
export 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
}

Source

Upload.vue

packages/ui/src/components/upload/Upload.vue

Upload — Slots
NameSignature or typeDescription
#trigger
{ selectFiles: (files: FileList | File[]) => Promise<void>; limit: number | undefined; multiple: boolean; accept: string | undefined; drag: boolean; }
Replaces the file-selection trigger area. Its scope provides selectFiles, limit, multiple, accept, and drag for custom controls.
Details

Declared type

{ selectFiles: (files: FileList | File[]) => Promise<void>; limit: number | undefined; multiple: boolean; accept: string | undefined; drag: boolean; }

Source

Upload.vue

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>; }
Replaces the file list. Its scope provides the current files, listType, and remove(file) and retry(file) actions.
Details

Declared type

{ 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>; }

Referenced types

UploadFile
Type definition — UploadFile
export 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
}

Source

Upload.vue

packages/ui/src/components/upload/Upload.vue

#default
{}
Renders additional content after the trigger and file list; it has no scoped parameters.
Details

Declared type

{}

Source

Upload.vue

packages/ui/src/components/upload/Upload.vue

Upload — Exposes
NameSignature or typeDescription
handleFileSelect
(files: FileList | File[]) => Promise<void>
Programmatically submits a FileList or File array through the same validation, beforeUpload, list update, and optional auto-upload flow.
Details

Declared type

(files: FileList | File[]) => Promise<void>

Source

Upload.vue:369

packages/ui/src/components/upload/Upload.vue

handleFileRemove
(file: UploadFile) => Promise<void>
Programmatically removes a file. The operation still honors beforeRemove and aborts an in-progress upload.
Details

Declared type

(file: UploadFile) => Promise<void>

Referenced types

UploadFile
Type definition — UploadFile
export 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
}

Source

Upload.vue:370

packages/ui/src/components/upload/Upload.vue

retryUpload
(file: UploadFile) => Promise<void>
Programmatically retries a file. Successful files are not retried, and the attempt is limited by maxRetries.
Details

Declared type

(file: UploadFile) => Promise<void>

Referenced types

UploadFile
Type definition — UploadFile
export 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
}

Source

Upload.vue:371

packages/ui/src/components/upload/Upload.vue

UploadFileItem

UploadFileItem — Props
NameTypeDefaultDescription
file
Required
UploadFile
—
The file to render, including its upload status, progress, and error details.
Details

Declared type

UploadFile

Referenced types

UploadFile
Type definition — UploadFile
export 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
}

Default value details

Not declared
—

Source

UploadFileItem.vue:24

packages/ui/src/components/upload/UploadFileItem.vue

listType
"text" | "picture" | "picture-card" | undefined
"text"
Selects the text, picture, or picture-card layout for this file item.
Details

Declared type

"text" | "picture" | "picture-card" | undefined

Literal values

  • "picture-card"
  • "picture"
  • "text"

Default value details

Declaration
'text'

Source: packages/ui/src/components/upload/UploadFileItem.vue

Resolved value
"text"

Source

UploadFileItem.vue:26

packages/ui/src/components/upload/UploadFileItem.vue

class
string | undefined
undefined
Custom CSS classes added to the file item root element.
Details

Declared type

string | undefined

Default value details

Declaration
undefined

Source: packages/ui/src/components/upload/UploadFileItem.vue

Resolved value
undefined

Source

UploadFileItem.vue:27

packages/ui/src/components/upload/UploadFileItem.vue

UploadFileItem — Events
NameSignature or typeDescription
@remove
[]
Emitted without a payload when the user activates the remove button; the parent handles removal.
Details

Declared type

[]

Source

UploadFileItem.vue

packages/ui/src/components/upload/UploadFileItem.vue

@retry
[]
Emitted without a payload only when the file is in error state and the user activates the retry button.
Details

Declared type

[]

Source

UploadFileItem.vue

packages/ui/src/components/upload/UploadFileItem.vue

UploadFileList

UploadFileList — Props
NameTypeDefaultDescription
files
Required
UploadFile[]
—
The file entries to render. The container is not rendered when the list is empty.
Details

Declared type

UploadFile[]

Referenced types

UploadFile
Type definition — UploadFile
export 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
}

Default value details

Not declared
—

Source

UploadFileList.vue:9

packages/ui/src/components/upload/UploadFileList.vue

listType
"text" | "picture" | "picture-card" | undefined
"text"
The text, picture, or picture-card layout applied to each file item.
Details

Declared type

"text" | "picture" | "picture-card" | undefined

Literal values

  • "picture-card"
  • "picture"
  • "text"

Default value details

Declaration
'text'

Source: packages/ui/src/components/upload/UploadFileList.vue

Resolved value
"text"

Source

UploadFileList.vue:11

packages/ui/src/components/upload/UploadFileList.vue

class
string | undefined
undefined
Custom CSS classes added to the file list container.
Details

Declared type

string | undefined

Default value details

Declaration
undefined

Source: packages/ui/src/components/upload/UploadFileList.vue

Resolved value
undefined

Source

UploadFileList.vue:12

packages/ui/src/components/upload/UploadFileList.vue

UploadFileList — Events
NameSignature or typeDescription
@remove
[file: UploadFile]
Forwards the corresponding UploadFile when a child item emits remove.
Details

Declared type

[file: UploadFile]

Referenced types

UploadFile
Type definition — UploadFile
export 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
}

Source

UploadFileList.vue

packages/ui/src/components/upload/UploadFileList.vue

@retry
[file: UploadFile]
Forwards the corresponding UploadFile when a child item emits retry.
Details

Declared type

[file: UploadFile]

Referenced types

UploadFile
Type definition — UploadFile
export 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
}

Source

UploadFileList.vue

packages/ui/src/components/upload/UploadFileList.vue

UploadTrigger

UploadTrigger — Props
NameTypeDefaultDescription
drag
boolean | undefined
true
Whether to handle file-drop events. When disabled, drops are ignored and the dragging state is cleared.
Details

Declared type

boolean | undefined

Literal values

  • false
  • true

Default value details

Declaration
true

Source: packages/ui/src/components/upload/UploadTrigger.vue

Resolved value
true

Source

UploadTrigger.vue:8

packages/ui/src/components/upload/UploadTrigger.vue

disabled
boolean | undefined
false
Disables file selection and dropping, and removes the trigger area from the keyboard tab order.
Details

Declared type

boolean | undefined

Literal values

  • false
  • true

Default value details

Declaration
false

Source: packages/ui/src/components/upload/UploadTrigger.vue

Resolved value
false

Source

UploadTrigger.vue:10

packages/ui/src/components/upload/UploadTrigger.vue

accept
string | undefined
undefined
The accept type hint passed to the hidden native file input.
Details

Declared type

string | undefined

Default value details

Declaration
undefined

Source: packages/ui/src/components/upload/UploadTrigger.vue

Resolved value
undefined

Source

UploadTrigger.vue:12

packages/ui/src/components/upload/UploadTrigger.vue

multiple
boolean | undefined
true
The multiple-selection setting passed to the native input. When false, both browsing and dropping keep only the first file.
Details

Declared type

boolean | undefined

Literal values

  • false
  • true

Default value details

Declaration
true

Source: packages/ui/src/components/upload/UploadTrigger.vue

Resolved value
true

Source

UploadTrigger.vue:14

packages/ui/src/components/upload/UploadTrigger.vue

class
string | undefined
undefined
Custom CSS classes added to the focusable trigger area.
Details

Declared type

string | undefined

Default value details

Declaration
undefined

Source: packages/ui/src/components/upload/UploadTrigger.vue

Resolved value
undefined

Source

UploadTrigger.vue:15

packages/ui/src/components/upload/UploadTrigger.vue

UploadTrigger — Events
NameSignature or typeDescription
@select
[files: File[], source: "browse" | "drop"]
Emitted with a non-empty file array after browsing or dropping, along with the browse or drop source. The array contains at most one file when multiple is false.
Details

Declared type

[files: File[], source: "browse" | "drop"]

Literal values

  • "browse"
  • "drop"

Source

UploadTrigger.vue

packages/ui/src/components/upload/UploadTrigger.vue

UploadTrigger — Slots
NameSignature or typeDescription
#default
{ isDragging: boolean; triggerFileInput: () => void; }
Replaces the entire trigger area. Its scope provides the live isDragging state and triggerFileInput() to open the file picker programmatically.
Details

Declared type

{ isDragging: boolean; triggerFileInput: () => void; }

Source

UploadTrigger.vue

packages/ui/src/components/upload/UploadTrigger.vue

#text
{}
Replaces the main prompt inside the built-in trigger area and is used when the default slot is absent. Without this slot, the source currently renders a hardcoded Chinese prompt meaning “Click or drop files here to upload”; this text is not locale-aware.
Details

Declared type

{}

Source

UploadTrigger.vue

packages/ui/src/components/upload/UploadTrigger.vue

#hint
{}
Replaces the helper text below the main prompt. The area is empty when this slot is not provided.
Details

Declared type

{}

Source

UploadTrigger.vue

packages/ui/src/components/upload/UploadTrigger.vue

Types ​

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
}

Accessibility ​

  • Keyboard: Trigger area is focusable and activatable with Enter / Space
  • ARIA Attributes: Hidden file input is properly labeled
  • Screen Readers: File status and progress are announced

Brute force builds.

© 2026 BrutxUI · MIT License