Upload

何时用

需要选/拖文件并展示带缩略图、状态、进度的文件列表时用。

分层（这是本组件的核心设计约束，别搞混）：

• <Upload> = 纯皮肤 + 状态展示。它仍然不做网络传输，只在通过 accept/maxSize/limit 校验后回 onSelect(File[])，其余状态靠受控 files 回填。
• useUpload({ request, concurrency }) = 传输层。队列、并发闸门、进度回填、取消、重传都在这里；但怎么发由你给的 request 决定。

request 的签名是 (file, { onProgress, signal }) => Promise<{ url }>。库内刻意没有 action / headers / withCredentials / transformResponse 这类参数——瑚琏是通用库，不给某一家后端的响应信封开后门，鉴权与解包请写在你的应用层闭包里。

落区形态用 variant="dropzone"，紧凑场景用 variant="button"。图片选完要裁剪请配合 ImageCropper；纯排序不涉及上传用 Sortable。

导入

Props

Events

Slots

UploadFile：{ id; name; size?; status?: "ready"\|"uploading"\|"success"\|"error"; progress?; error?; url?; raw? } · progress 仅 status="uploading" 时展示进度条 + 百分比（内部 clamp 到 0-100） · url / raw 都是纯附加字段，不参与组件内部逻辑，只供 renderPreview 与你自己回读；onSelect 仍然给 File[]，File 语义没被替换

useUpload（传输层）

禁忌 / 坑

• <Upload> 不会自己上传。要自动上传就配 useUpload；坚持自己管，就把 status/progress/error/url 回填到受控 files。
• 不给 `name` 就没有原生表单这条路：没有 name 的 input 压根不出现在 FormData 的 entries 里，required 也不会被浏览器校验。这两件事都不会报错，只是静默不生效。
• 挂了 name 后有三处默认行为跟着变（都只在有 name 时发生）：① 选完不再清 value（否则 FormData 永远读到空），代价是同一个文件连选两次不会再触发 `onSelect`——要那个行为就显式写 resetInputAfterSelect，但那样 FormData 就读不到了，二者不可兼得；② 拖入的文件会被写回 input.files（原生拖放不会自己进去），同时被 accept/maxSize/limit 拒掉的文件会被剔出去，避免「界面说拒了、表单照样提交」；③ 达到 limit 时 input 不跟着禁用——禁用控件会被 FormData 整个跳过，已选的文件会在提交时凭空消失（触发器那侧照旧禁用，点不开选择框）。
• 写回 input.files 依赖 DataTransfer 构造器。测试环境（jsdom）没有它，回写会静默跳过，onSelect 那条路不受影响——别在 jsdom 里断言拖入后的 `FormData` 内容。
• 失败行的重试按钮要传 `onRetry` 才出现。useUpload 早就有 retry，但组件不替你决定「这个失败该不该给重试入口」——直接 onRetry={up.retry} 接上即可。
• 不要指望库帮你解后端信封。request 拿到的 { url } 是你自己 resolve 的，code/data/msg 之类的形状在你的闭包里剥完再返回。
• sortable 单独给不生效，必须同时给 `onSort`（顺序是受控的，组件不偷存）；只给 sortable 会静默退回静态列表。
• renderPreview 每次渲染都会被调用，别在里面直接 `URL.createObjectURL` —— 会漏对象 URL。缓存到 Map<id, url> 并在卸载时 revokeObjectURL（showcase 的 useObjectUrls 是可抄的写法）。
• limit 按受控 files.length 算；files 没传时视为 0，此时 limit 只能拦住"单次选太多"，拦不住累计。
• useUpload 的 remove 会 abort()，但只有你把 `signal` 透传下去才真取消；迟到的 resolve 会被丢弃，不会复活已移除的行。
• 引入 sortable 让 upload 静态依赖了 @dnd-kit/*（与 Sortable/Kanban 同源），source 分发下不用 sortable 也会打进包里。
• 必填对辅助技术的表达走说明文本，不是 aria-required（#294）：落区是 role="button"、button 形态是真 <button>，而 aria-required 在 ARIA 里只对输入型 role 有效，挂上去读屏不会念。传 required（或把 Upload 放进 <Field required>）时，触发器会串上一段 sr-only 的「必填」说明。
• <Field required> 只给语义标记，不打开原生 required 校验 —— 要浏览器拦下提交，仍需自己传 required 且同时给 name。
• 落区自己的 aria-describedby 串的是 hint 与必填说明，Field 的 description / error 不走这条路：说明文案请用组件的 hint。

相关

Sortable · ImageCropper · SecretField · Combobox · Listbox · Progress