FileUpload 文件上传
选择或拖放本地文件，并展示队列、进度、错误与移除操作。
使用概览
适合使用
- 用户需要上传一个或多个文件且必须了解每项处理状态时。
不建议使用
- 只需要输入现有文件网址，或应用无法提供真实上传传输逻辑时。
真实示例
PDF 文件上传
限制 PDF 类型并把选中文件交给调用方队列。
正在加载示例…
安装
本地候选警告Registry 地址仅指向当前本地文档站；npm 包也只用于本地候选验证，尚未公开发布。
pnpm dlx shadcn@4.16.0 add http://127.0.0.1:3000/r/file-upload.json基础用法
导入
import { FileUpload } from "@richardqiu/quartz/file-upload";JSX
<FileUpload accept="application/pdf" browseLabel="选择 PDF 文件" items={[]} maxFiles={3} onFilesSelected={() => undefined} removeLabel={(item) => `移除 ${item.name}`} />状态与控制摘要
默认
悬停
键盘焦点可见
加载中
错误
已禁用
label · textactive · booleanAPI 参考
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
items | readonly FileUploadItem[] | 必填 | 由调用方提供每个文件的名称、大小与上传状态。 |
onFilesSelected | (files: readonly File[]) => void | 必填 | 把通过校验的本地文件交给调用方上传逻辑。 |
组合结构
- 01
FileUpload
键盘约定
- Enter 或空格键打开原生文件选择器，Tab 访问重试与移除操作。
可访问性契约
- 每个受控文件都暴露进度和错误。
- 被拒文件给出稳定的类型、大小或数量原因。