Upload

upload

文件上传 · 拖拽落区/按钮形态 + accept/maxSize 校验 + 受控文件列表(状态/进度)，零依赖自研只发 onSelect

用法

基础用法（拖拽落区）

默认 dropzone 形态：点击或拖拽文件，校验通过的文件经 onSelect 抛出，状态/进度由消费者回填到 files。

点击或拖拽文件到此处

支持任意格式，单文件 ≤ 5MB

tsx

<Upload
  multiple
  hint="支持任意格式，单文件 ≤ 5MB"
  maxSize={5 * 1024 * 1024}
  files={files}
  onSelect={(picked) => /* 上传并回填 files */}
  onRemove={(id) => /* 移除 */}
/>

按钮形态

variant="button" 收成单按钮，accept 限定文件类型。

tsx

<Upload variant="button" accept="image/*" buttonLabel="上传头像" />

文件列表与状态

files 受控展示：success / uploading（带进度条）/ error（带错误文案）三态共存。

report-2026.pdf1.8 MB
cover.png
huge-video.mov超过 5MB 上限

tsx

const files = [
  { id: "a", name: "report-2026.pdf", size: 1.8 * 1024 * 1024, status: "success" },
  { id: "b", name: "cover.png", size: 820 * 1024, status: "uploading", progress: 62 },
  { id: "c", name: "huge-video.mov", status: "error", error: "超过 5MB 上限" },
];

<Upload variant="button" files={files} onRemove={(id) => remove(id)} />

禁用态

点击或拖拽文件到此处

已禁用

tsx

<Upload disabled hint="已禁用" />

何时用

需要选/拖文件并展示带状态进度的文件列表时用。注意：组件不做网络传输，它只在通过 accept/maxSize 校验后回 onSelect，真正上传、进度回填由消费者完成（受控 files）。落区形态用 variant="dropzone"，紧凑场景用 variant="button"。图片选完要裁剪请配合 ImageCropper。

导入

import { Upload, matchesAccept } from "@hulianui/ui"

Props

名称	类型	默认	说明
accept	`string`	—	原生 accept（如 `"image/*,.pdf"`）；同时用于落区校验
multiple	`boolean`	`false`	是否允许多选
disabled	`boolean`	`false`	禁用
maxSize	`number`	—	单文件字节上限；超限进 `onReject(reason="size")`
variant	`"dropzone" \| "button"`	`"dropzone"`	形态：拖拽落区 / 单按钮
files	`UploadFile[]`	—	受控展示的文件列表（含状态/进度）；不传则不渲染列表
className	`string`	—	容器类名

Events

事件	类型	说明
onSelect	`(files: File[]) => void`	通过校验的文件被选中（点击选择或拖入）
onReject	`(rejections: UploadRejection[]) => void`	被校验拒绝的文件（类型/大小）
onRemove	`(id: string) => void`	列表项移除按钮点击

Slots

插槽	类型	说明
label	`ReactNode`	落区主文案
hint	`ReactNode`	落区辅助说明（格式/大小限制提示）
buttonLabel	`ReactNode`	button 形态的按钮文案（默认 `"选择文件"`）
children	`ReactNode`	自定义落区内容（覆盖 label/hint）

UploadFile：{ id; name; size?; status?: "ready"\|"uploading"\|"success"\|"error"; progress?; error? }，progress 仅 status="uploading" 时展示进度条。

禁忌 / 坑

组件只发 onSelect，不会自己上传。进度条/成功/失败态全靠消费者把 UploadFile.status/progress/error 回填到受控 files。
想知道某文件为何被拒（类型 vs 大小）接 onReject，reason 区分 "size"/"type"。
暂无其它已知坑。

Playground

variantmultipledisabled

点击或拖拽文件到此处

支持任意格式

<Upload
  variant="dropzone"
  multiple
  maxSize={5 * 1024 * 1024}
  files={files}
  onSelect={(picked) => /* 上传并回填 files */}
  onRemove={(id) => /* 移除 */}
/>

用法

基础用法（拖拽落区）

默认 dropzone 形态：点击或拖拽文件，校验通过的文件经 onSelect 抛出，状态/进度由消费者回填到 files。

点击或拖拽文件到此处

支持任意格式，单文件 ≤ 5MB

tsx

<Upload
  multiple
  hint="支持任意格式，单文件 ≤ 5MB"
  maxSize={5 * 1024 * 1024}
  files={files}
  onSelect={(picked) => /* 上传并回填 files */}
  onRemove={(id) => /* 移除 */}
/>

按钮形态

variant="button" 收成单按钮，accept 限定文件类型。

tsx

<Upload variant="button" accept="image/*" buttonLabel="上传头像" />

文件列表与状态

files 受控展示：success / uploading（带进度条）/ error（带错误文案）三态共存。

report-2026.pdf1.8 MB
cover.png
huge-video.mov超过 5MB 上限

tsx

const files = [
  { id: "a", name: "report-2026.pdf", size: 1.8 * 1024 * 1024, status: "success" },
  { id: "b", name: "cover.png", size: 820 * 1024, status: "uploading", progress: 62 },
  { id: "c", name: "huge-video.mov", status: "error", error: "超过 5MB 上限" },
];

<Upload variant="button" files={files} onRemove={(id) => remove(id)} />

禁用态

点击或拖拽文件到此处

已禁用

tsx

<Upload disabled hint="已禁用" />

何时用

Props

名称	类型	默认	说明
accept	`string`	—	原生 accept（如 `"image/*,.pdf"`）；同时用于落区校验
multiple	`boolean`	`false`	是否允许多选
disabled	`boolean`	`false`	禁用
maxSize	`number`	—	单文件字节上限；超限进 `onReject(reason="size")`
variant	`"dropzone" \| "button"`	`"dropzone"`	形态：拖拽落区 / 单按钮
files	`UploadFile[]`	—	受控展示的文件列表（含状态/进度）；不传则不渲染列表
className	`string`	—	容器类名

事件

类型

说明

onSelect

(files: File[]) => void

通过校验的文件被选中（点击选择或拖入）

onReject

(rejections: UploadRejection[]) => void

被校验拒绝的文件（类型/大小）

onRemove

(id: string) => void

列表项移除按钮点击

Slots

插槽	类型	说明
label	`ReactNode`	落区主文案
hint	`ReactNode`	落区辅助说明（格式/大小限制提示）
buttonLabel	`ReactNode`	button 形态的按钮文案（默认 `"选择文件"`）
children	`ReactNode`	自定义落区内容（覆盖 label/hint）

UploadFile：{ id; name; size?; status?: "ready"\|"uploading"\|"success"\|"error"; progress?; error? }，progress 仅 status="uploading" 时展示进度条。

Upload

用法

基础用法（拖拽落区）

按钮形态

文件列表与状态

禁用态

何时用

导入

Props

Events

Slots

禁忌 / 坑

相关

Playground

Upload

用法

基础用法（拖拽落区）

按钮形态

文件列表与状态

禁用态

何时用

导入

Props

Events

Slots

禁忌 / 坑

相关

Playground