Upload

基础表单

基于 Bootstrap 5 的上传组件，提供文件选择、拖拽上传、数量与大小限制、上传前校验与内置文件列表，并支持受控文件列表、自定义触发器与列表，配合 UploadItem / UploadList / useUpload 灵活组合上传流程

Component Demo

Basic usage and examples of the Upload component

基础用法

Upload files

默认渲染内置的上传按钮与文件列表，选择文件后以列表条目展示名称与大小，可单独移除

拖拽上传

点击选择文件，或将文件拖拽到此处上传

dropzone 开启后触发器渲染为虚线拖放区，支持点击选择与拖拽投放两种方式，拖拽悬停时高亮

多选与文件类型

Upload files

multiple 允许一次选择多个文件；accept 限制文件选择对话框中的可选类型（拖拽文件不受影响，可通过 beforeUpload 过滤）

禁用状态

Upload files

disabled 禁用后无法打开文件选择，也无法移除已有条目

数量与大小限制

Upload files

maxCount 限制最多 3 个文件，达到上限后触发器不可用；maxSize 限制单个文件不超过 1MB，超出的文件以错误状态进入列表，可移除后继续选择

上传前校验

Upload files

beforeUpload 对每个候选文件调用，返回 false 时该文件被拒绝；已拒绝：无。也支持返回 Promise 进行异步校验

受控模式

Upload files

传入 files 后组件不再维护内部状态，列表完全由外部控制，onFilesChange 反馈每次新增与移除后的最新列表

自定义触发器

children 自定义触发器内容，整个触发器区域点击均可唤起文件选择；内部交互元素需 stopPropagation 后通过 useUpload 的 openFileDialog 打开

自定义列表

选择文件

showUploadList 设为 false 关闭内置列表后，可改用 UploadList 与 UploadItem 在任意位置手动渲染文件条目

模拟上传进度

Upload files

通过受控 files 更新每个条目的 status 与 percent，即可驱动上传中进度条、成功/失败图标等状态展示

API Documentation

Complete API reference for the Upload component

Props

Upload

属性名	类型	默认值	描述
`accept`	`string`	-	原生 `input` 的 `accept` 属性，限制文件选择对话框中的可选文件类型；拖拽文件不受其约束，可配合 `beforeUpload` 过滤
`as`	`ElementType`	`'div'`	根容器渲染的元素类型
`beforeUpload`	`UploadBeforeUpload`	-	上传前校验，对每个候选文件调用；返回 `false`（或 `resolve(false)`）时该文件被拒绝，不会进入文件列表
`capture`	`boolean \| 'environment' \| 'user'`	-	原生 `input` 的 `capture` 属性，移动端可直接唤起相机等设备
`children`	`ReactNode`	-	自定义触发器内容，默认渲染内置上传按钮（拖拽模式下为拖拽提示区）
`className`	`string`	-	自定义类名，作用于根容器
`defaultFiles`	`UploadFile[]`	`[]`	非受控模式下的初始文件列表
`disabled`	`boolean`	`false`	是否禁用整个上传组件，禁用后无法打开文件选择且无法移除文件
`dropzone`	`boolean`	`false`	是否启用拖拽上传区域，此时触发器渲染为虚线框拖放区
`files`	`UploadFile[]`	-	受控的文件列表，配合 `onFilesChange` 使用；传入后组件不再维护内部状态
`itemProps`	`Omit<UploadItemProps, 'file'>`	-	透传给内置列表中每个 `UploadItem` 的属性（`file` 除外）
`listProps`	`Omit<UploadListProps, 'children'>`	-	透传给内置 `UploadList` 的属性（`children` 除外）
`maxCount`	`number`	-	最多允许的文件数量，达到上限后触发器不可用；超出限制大小的错误项同样计入数量
`maxSize`	`number`	-	单个文件的最大字节数，超出时该文件以 `error` 状态进入列表并附带错误信息
`multiple`	`boolean`	`false`	是否允许一次选择多个文件
`name`	`string`	-	原生 `input` 的 `name` 属性，用于表单提交
`onFilesChange`	`(files: UploadFile[]) => void`	-	文件列表变化（新增或移除）时的回调，携带最新的完整文件列表
`showUploadList`	`boolean`	`true`	是否渲染内置文件列表；设为 `false` 时可改用 `UploadList` / `UploadItem` 手动渲染
`...rest`	`HTMLAttributes`	-	根容器的所有原生属性（`onChange` 除外，内部 input 的变更通过 `onFilesChange` 暴露）

UploadItem

属性名	类型	默认值	描述
`as`	`ElementType`	`'li'`	渲染的元素类型
`children`	`ReactNode`	-	信息列内附加的自定义内容
`className`	`string`	-	自定义类名
`file`	`UploadFile`	-	要渲染的文件记录，status 决定图标、进度条与错误提示的展示
`onRemove`	`(file: UploadFile) => void`	-	移除回调；位于 `Upload` 内部时默认使用上下文的移除逻辑，独立使用时需手动传入
`...rest`	`HTMLAttributes`	-	根元素的所有原生属性（如 `style`、`data-*` 等）

UploadList

属性名	类型	默认值	描述
`as`	`ElementType`	`'ul'`	渲染的元素类型
`children`	`ReactNode`	-	列表内容，通常为多个 `UploadItem`
`className`	`string`	-	自定义类名，可配合 `mt-*` 等工具类调整间距
`...rest`	`HTMLAttributes`	-	根元素的所有原生属性（如 `style`、`aria-*` 等）

Type Definitions

UploadBeforeUpload

上传前校验函数类型，支持同步返回与异步 Promise

export type UploadBeforeUpload = (file: File, files: UploadFile[]) => boolean | Promise<boolean>;

UploadContextValue

上传上下文值，可通过 `useUpload` 获取（不在 `Upload` 内返回 `null`）

export interface UploadContextValue {
  accept?: string;
  beforeUpload?: UploadBeforeUpload;
  disabled: boolean;
  files: UploadFile[];
  handleRemove: (file: UploadFile) => void;
  maxCount?: number;
  maxSize?: number;
  multiple: boolean;
  openFileDialog: () => void;
}

UploadFile

文件记录结构，`raw` 保留原生 File 对象以便自行上传

export interface UploadFile {
  error?: string;
  name: string;
  percent?: number;
  raw?: File;
  size?: number;
  status?: UploadStatus;
  uid: string;
  url?: string;
}

UploadItemProps

文件条目组件属性接口

export interface UploadItemProps extends HTMLAttributes<HTMLElement> {
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  file: UploadFile;
  onRemove?: (file: UploadFile) => void;
}

UploadListProps

文件列表组件属性接口

export interface UploadListProps extends HTMLAttributes<HTMLElement> {
  as?: ElementType;
  children?: ReactNode;
  className?: string;
}

UploadProps

上传组件属性接口

export interface UploadProps extends Omit<HTMLAttributes<HTMLElement>, 'onChange'> {
  accept?: string;
  as?: ElementType;
  beforeUpload?: UploadBeforeUpload;
  capture?: boolean | 'environment' | 'user';
  children?: ReactNode;
  className?: string;
  defaultFiles?: UploadFile[];
  disabled?: boolean;
  dropzone?: boolean;
  files?: UploadFile[];
  itemProps?: Omit<UploadItemProps, 'file'>;
  listProps?: Omit<UploadListProps, 'children'>;
  maxCount?: number;
  maxSize?: number;
  multiple?: boolean;
  name?: string;
  onFilesChange?: (files: UploadFile[]) => void;
  showUploadList?: boolean;
}

UploadStatus

文件状态类型，驱动条目的图标、进度条与错误提示

export type UploadStatus = 'error' | 'ready' | 'success' | 'uploading';