组件 · 数据录入

Upload 上传

文件上传触发与列表；适配器能力以公开导出为准（HTTP/OSS 等）。只收录已验证适配器，不编造存储后端。

入口 @selrux/ui/upload · 源码 src/components/upload/index.ts · 4 个组件 · 发布状态 preview

使用建议

避免：杜撰未导出的存储适配器
避免：把 Upload 当成业务附件中心
限制：适配器与凭证由应用注入；知识不提供凭据

引入

tsx

123456789import {
  Upload,
  UploadDragger,
  UploadList,
  UploadTrigger,
  adapterResultToFilePatch,
  applyAdapterResultToFile,
  // …共 30 个导出
} from '@selrux/ui/upload';

演练场

调节下方可实现的字面量属性，实时预览真实组件。函数、Portal、样式逃生口等见代码演示与 API 表。

代码演示

基础用法

customRequest 接管上传。本演示在浏览器内模拟进度后标记完成，不发送网络请求。

已有文件列表

defaultFileList 展示已上传与失败的文件。

需求说明.pdf200.0 KB

截图.pngUpload failed

列表形态

listMode 为 text / attachment / picture-card。

合同.docx100.0 KB

受控文件列表

fileList / onChange 受控；accept 限制类型；maxCount 限制数量；beforeUpload 返回 false 拦截（这里拦截超过 2MB 的文件）；onRemove 可异步确认删除；onPreview 自定义预览；size 尺寸。

营业执照.jpg312.5 KB

1 个文件

触发按钮与列表

UploadTrigger 的 color / size / loading / loadingLabel；disabled 禁用上传；showUploadList={false} 隐藏内置列表；listRender 自定义列表渲染。

季度汇总.xlsx

API

属性覆盖：示例用到 20 / 22 个自有属性（90.9%）

由 scripts/demo-coverage.mjs 统计，不含 className / style / 原生透传属性与纯转发事件。

Upload.adapter：需要真实存储后端（HTTP / tusd / OSS / COS / 七牛）；文档站为静态站点，示例统一用 customRequest 模拟
Upload.adapterOptions：同 adapter：需要真实存储后端
Upload.action：需要真实上传接口；静态站点无后端，选择文件会产生失败请求
Upload.name：上传请求的表单字段名，仅在真实请求中可见
Upload.method：上传请求的 HTTP 方法，仅在真实请求中可见
Upload.headers：上传请求头，仅在真实请求中可见
Upload.data：上传请求附加字段，仅在真实请求中可见
Upload.withCredentials：跨域请求携带凭据，仅在真实请求中可见

Upload

主题化 Upload。默认在未显式放置 UploadList 且 showUploadList 时，自动追加文件列表。

属性	说明	类型	默认值
`size`	六档视觉尺寸；同步到默认 Attachment 列表与 Trigger。	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	`Attachment`
`listMode`	默认列表展示模式。 `listRender` 存在时忽略本字段。	`"text" \| "attachment" \| "picture-card"`	-
`fileList`	受控文件列表。	`UploadFileInfo[]`	-
`defaultFileList`	非受控默认列表。	`UploadFileInfo[]`	-
`onChange`	列表变化。	`((info: UploadChangeParam) => void)`	-
`adapter`	适配器种类或自定义适配器。云厂商 SDK 在首次上传时动态懒加载。	`UploadAdapter \| UploadAdapterKind`	-
`adapterOptions`	适配器配置（endpoint、getCredentials 等）。	`unknown`	-
`action`	HTTP action（adapter=http 时使用）。	`string \| ((file: File) => string \| Promise<string>)`	-
`name`	表单字段名。	`string`	-
`method`	HTTP 方法。	`"POST" \| "PUT" \| "PATCH" \| "post" \| "put" \| "patch"`	-
`headers`	请求头。	`Record<string, string> \| ((file: File) => Record<string, string> \| Promise<Record<string, string>>)`	-
`data`	额外字段。	`Record<string, unknown> \| ((file: File) => Record<string, unknown> \| Promise<Record<string, unknown>>)`	-
`withCredentials`	是否携带 cookie。	`boolean`	-
`customRequest`	完全自定义上传；优先于 adapter。	`((options: UploadCustomRequestOptions) => void \| Promise<void>)`	-
`beforeUpload`	上传前钩子；返回 false 阻止。	`((file: File, fileList: File[]) => UploadBeforeUploadResult)`	-
`multiple`	多选。	`boolean`	-
`accept`	accept 字符串。	`string`	-
`maxCount`	最大文件数；为 1 时替换。	`number`	-
`maxConcurrent`	同时传输的文件数上限（有界并发队列），与 `maxCount`（列表长度）无关。缺省不限（保持旧行为）；超出的文件保持 pending 排队，暂停的文件不占槽位。	`number`	-
`retainUploadsOnUnmount`	卸载时是否保留在途上传（默认 false）。 false：卸载时解除本地传输并清空队列，不终止服务端资源（可日后用同一会话恢复）； true：不做任何清理，由所有者（如应用级上传中心）负责在合适时机通过控制器 `destroy` 释放。	`boolean`	`false`
`disabled`	禁用。	`boolean`	-
`showUploadList`	是否展示默认列表区域（由 UI 解释）。	`boolean`	-
`onRemove`	移除钩子；返回 false 阻止。	`((file: UploadFileInfo) => void \| boolean \| Promise<void \| boolean>)`	-
`onPreview`	点击预览。图片默认走 ImagePreviewGroup；返回 `false` 可阻止。非图片无内置预览，由此回调扩展视频 / Word / PPT / Excel / md 等。	`UploadPreviewHandler`	-
`onDrop`	拖拽放下时额外回调。	`((event: DragEvent<HTMLElement>) => void)`	-
`listRender`	自定义列表。	`UploadListRender`	-
`children`	触发区与列表外的子节点。	`ReactNode`	-

另有 277 项原生属性与事件继承自 HTMLAttributes，原样透传。

UploadDragger

主题化拖拽区。

无自有属性；其余 280 项原生属性继承自 HTMLAttributes。

UploadList

主题化列表槽。无 children 且无 listRender 时渲染默认文件列表。

属性	说明	类型	默认值
`children`	覆盖根上的 listRender。	`ReactNode`	-

另有 279 项原生属性与事件继承自 HTMLAttributes，原样透传。

UploadTrigger

上传触发器：复用本库 Button（非 block）。点击打开文件选择；尺寸默认跟随 Upload。

属性	说明	类型	默认值
`color`	语义色。省略为 primary。	`"info" \| "success" \| "warning" \| "primary" \| "destructive" \| "carbon" \| "secondary" \| "accent"`	`primary`
`variant`	展示方式。省略为 solid。	`"link" \| "outline" \| "ghost" \| "solid"`	`solid`
`size`	尺寸。省略时使用 ConfigProvider，无配置时为 md。	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	-
`loading`	为真时阻止再次激活，并保留动作名称和焦点。	`boolean`	`false`
`loadingLabel`	忙碌辅助说明。省略时使用当前语言包。	`string`	-
`children`	按钮内容。图标作为子节点组合。	`ReactNode`	-

另有 288 项原生属性与事件继承自 ButtonHTMLAttributes / HTMLAttributes，原样透传。

导出类型：AliyunOssAdapterOptions、AliyunOssCredentials、HttpAdapterOptions、QiniuAdapterOptions、QiniuCredentials、TencentCosAdapterOptions、TencentCosCredentials、TusdAdapterOptions、UploadAdapter、UploadAdapterKind、UploadAdapterRequest、UploadAdapterResult、UploadBeforeUploadResult、UploadChangeParam、UploadCustomRequestOptions、UploadDraggerProps、UploadFileInfo、UploadFileStatus、UploadListActions、UploadListMode、UploadListProps、UploadListRender、UploadPreviewHandler、UploadProps、UploadResultMapContext、UploadResultMapper、UploadSize、UploadTriggerProps

函数与常量

名称	说明	签名 / 类型
`adapterResultToFilePatch`	将归一结果转为可合并进列表项的字段补丁。	`(result: UploadAdapterResult) => Partial<UploadFileInfo>`
`applyAdapterResultToFile`	把适配器结果合并进已有列表项，并标记 done。	`(file: UploadFileInfo, result: UploadAdapterResult) => UploadFileInfo`
`coerceSuccessToAdapterResult`	兼容 customRequest 的 onSuccess(response, url)。优先识别 `UploadAdapterResult`；否则用 url 参数或 response.url。	`(resultOrResponse: unknown, urlArg: string \| undefined, file: UploadFileInfo) => UploadAdapterResult`
`createAliyunOssAdapter`	创建阿里云 OSS 适配器。首次 upload 时动态 import；可用 `mapResult` 改写统一结构。	`(options: AliyunOssAdapterOptions) => UploadAdapter`
`createHttpAdapter`	创建默认 HTTP（XHR）适配器。支持 `mapResult` 将业务响应转为统一 `UploadAdapterResult`。	`(options?: HttpAdapterOptions) => UploadAdapter`
`createQiniuAdapter`	创建七牛云适配器。首次 upload 时动态 import；可用 `mapResult` 改写统一结构。	`(options: QiniuAdapterOptions) => UploadAdapter`
`createTencentCosAdapter`	创建腾讯云 COS 适配器。首次 upload 时动态 import；可用 `mapResult` 改写统一结构。	`(options: TencentCosAdapterOptions) => UploadAdapter`
`createTusdAdapter`	创建 tusd（tus-js-client）适配器。首次 upload 时动态 import；可用 `mapResult` 改写统一结构。控制语义： - `pause` / `resume`：`upload.abort(false)` / `upload.start()`，不终止服务端资源； - `abort(uid)` 与 signal 中止：`upload.abort(true)` 终止服务端资源，幂等，同一 uid 只终止一次； - `destroy()`：由所有者决定，默认仅解除本地传输、保留服务端资源。鉴权只通过注入的 `getHeaders` / `onBeforeRequest` 进入请求，库本身不持有令牌。	`(options: TusdAdapterOptions) => UploadAdapter`
`createUploadFileInfoFromFile`	从 File 创建统一列表项；图片会生成本地 blob 缩略图。	`(file: File, uid?: string) => UploadFileInfo`
`createUploadUid`	生成文件 uid。	`() => string`
`describeUploadFile`	列表说明文案。	`(file: UploadFileInfo) => string`
`disposeUploadFile`	移除前清理 blob。	`(file: UploadFileInfo) => void`
`fileToUploadInfo`	将 File 转为统一列表项（含图片本地 blob 缩略图）。	`(file: File, uid?: string) => UploadFileInfo`
`formatUploadFileSize`	人类可读文件大小。	`(size: number \| undefined) => string`
`isUploadAdapterResult`	判断是否为归一的适配器结果。	`(value: unknown) => value is UploadAdapterResult`
`isUploadPreviewableImage`	是否为可默认预览的图片（有可显示地址）。	`(file: UploadFileInfo) => boolean`
`normalizeUploadFile`	规范化外部传入的列表项。	`(file: UploadFileInfo) => UploadFileInfo`
`resolveUploadAdapter`	按 kind 解析内置适配器；自定义对象直接返回。	`(adapter: UploadAdapterKind \| UploadAdapter \| undefined, adapterOptions: unknown, httpFallback: HttpAdapterOptions) => UploadAdapter`
`resolveUploadListMode`	解析列表模式；非法值回落 attachment。	`(mode: UploadListMode \| undefined) => UploadListMode`
`resolveUploadSize`	解析 Upload 尺寸。	`(size: UploadSize \| undefined, configured: ControlSize \| undefined) => UploadSize`
`revokeUploadThumbUrl`	释放由本库创建的 blob 缩略图。	`(file: UploadFileInfo) => void`
`transformAdapterResult`	用 `mapResult`（若有）把原始响应转为统一的 `UploadAdapterResult`。无转换器时返回 `defaults`。	`<TRaw>(raw: TRaw, ctx: UploadResultMapContext, mapResult?: UploadResultMapper<TRaw>) => UploadAdapterResult`
`uploadStatusToAttachmentState`	Upload status → Attachment state（契约见 56-upload）。 `paused` 映射为 `idle`：表示未在传输，但非完成；与 Headless 测试约定一致。不得把 `paused` 落到 default→`done`。	`(status: UploadFileStatus \| undefined) => AttachmentState`
`useUploadContext`	读取 Upload 上下文；在根外调用时抛错。	`() => UploadContextValue`
`useUploadController`	管理 fileList、有界并发上传调度、暂停 / 恢复 / 重试与取消。受控时以 fileList prop 为准；非受控维护内部状态。暂停保留服务端资源；取消（abort / remove）才终止；卸载默认只解除本地传输、不终止服务端资源。	`(input: UseUploadControllerInput) => UploadController`
`visibleUploadFiles`	可见列表（排除 removed）。	`(fileList: UploadFileInfo[]) => UploadFileInfo[]`

摘自源码 JSDoc。

UploadTrigger.loading：为真时阻止再次激活，并保留动作名称和焦点。