Upload 上传

• 组件说明：拖拽上传区域，内置文件上传能力，管理文件队列的进度、状态与操作。
• 组件组：Atomic
• 实现约定：纯 Design 层组件，无 ui/ primitive。支持 action / customRequest / beforeUpload 上传生命周期（类似 antd Upload API）。
• Figma 规范：Upload Drags (21244:1609)

基础用法

空状态拖拽区域 — 点击或拖拽选择文件。提供 action 或 customRequest 即可启用自动上传。

结果

Loading...

实时编辑器

const Demo = () => {
  const [fileList, setFileList] = React.useState([]);
  return (
    <div style={{ maxWidth: 660 }}>
      <Upload
        hint="点击或拖拽音频文件上传"
        accept="audio/*,video/*"
        fileList={fileList}
        onChange={({ fileList: newList }) => setFileList(newList)}
      />
    </div>
  );
};
render(<Demo />);

文件队列

选择文件后，拖拽区域收缩为紧凑模式，下方显示文件列表。

结果

Loading...

实时编辑器

const Demo = () => {
  const [fileList, setFileList] = React.useState([
    { uid: '1', name: '想法与方案', size: 5600000, status: 'uploading', percent: 57 },
    { uid: '2', name: '02_22 下午会议 4月22日', size: 12400000, status: 'error' },
    { uid: '3', name: '0820 下午会议', size: 3700000, status: 'done' },
  ]);
  return (
    <div style={{ maxWidth: 660 }}>
      <Upload
        hint="或拖拽音频文件上传"
        description={
          <>
            最大文件时长：<strong>5 小时</strong>
            <br />
            支持 audio/*、video/*、.rmvb、.rm、.divx、.ts、.m2ts、.3gp、.f4v、.asr
          </>
        }
        fileList={fileList}
        onChange={({ fileList: newList }) => setFileList(newList)}
      />
    </div>
  );
};
render(<Demo />);

自动上传

提供 action（URL）或 customRequest 可在选择文件后自动上传。

结果

Loading...

实时编辑器

const Demo = () => {
  const [fileList, setFileList] = React.useState([]);
  return (
    <div style={{ maxWidth: 660 }}>
      <Upload
        hint="点击或拖拽音频文件上传"
        action="https://httpbin.org/post"
        fileList={fileList}
        onChange={({ file, fileList: newList }) => {
          setFileList(newList);
        }}
      />
    </div>
  );
};
render(<Demo />);

禁用状态

结果

Loading...

实时编辑器

render(
  <div style={{ maxWidth: 660 }}>
    <Upload hint="点击或拖拽音频文件上传" disabled />
  </div>,
)

自定义图标

通过 icon prop 替换默认云图标，传 null 可隐藏图标。

结果

Loading...

实时编辑器

render(
  <div style={{ maxWidth: 660 }}>
    <Upload icon={<span style={{ fontSize: 48 }}>📁</span>} hint="拖拽文件到此处" />
  </div>,
)

beforeUpload 校验

使用 beforeUpload 在上传前校验或转换文件，返回 false 可阻止上传。

结果

Loading...

实时编辑器

const Demo = () => {
  const [fileList, setFileList] = React.useState([]);
  return (
    <div style={{ maxWidth: 660 }}>
      <Upload
        hint="仅允许 10MB 以下文件"
        fileList={fileList}
        beforeUpload={(file) => {
          if (file.size > 10 * 1024 * 1024) {
            alert('文件过大！');
            return false;
          }
          return true;
        }}
        onChange={({ fileList: newList }) => setFileList(newList)}
      />
    </div>
  );
};
render(<Demo />);

尺寸 Token

Token	值	用途
--Radius_5	5px	Dropzone / FileItem 圆角
--Spacing_4	4px	文件列表间距、状态图标间距
--Spacing_8	8px	FileItem 内边距、元信息间距
--Spacing_16	16px	Dropzone 与文件列表间距
--Spacing_24	24px	内容与操作按钮间距

颜色 Token

Token	值	用途
--Labels-Secondary	#3d3d3d	文件名、提示文案
--Labels-Tertiary	#757575	文件大小、状态文案
--Labels-Link	#0066cc	紧凑模式 "Click" 链接色
--Grays-Gray_1	#ebebeb	拖拽悬停背景
--Grays-Gray_2	#d6d6d6	进度条轨道
--Grays-Gray_7	#333333	进度条指示器
--Status-Destructive	#ff503f	失败状态图标

Props

属性	类型	默认值	说明
fileList	UploadFile[]	—	受控文件列表
defaultFileList	UploadFile[]	[]	非受控默认文件列表
action	string | ((file: File) => Promise<string>)	—	上传地址
customRequest	(option: UploadRequestOption) => { abort }	—	自定义上传请求
headers	Record<string, string>	—	自定义请求头
data	Record | ((file) => Record)	—	附加上传数据
name	string	'file'	文件字段名
method	string	'POST'	HTTP 方法
withCredentials	boolean	—	是否携带 cookie
accept	string	—	文件输入 accept 属性
multiple	boolean	true	允许多文件选择
maxCount	number	—	最大文件数量
beforeUpload	(file, fileList) => boolean | File | Promise	—	上传前校验；返回 false 阻止
onChange	(info: { file, fileList }) => void	—	状态变化回调
onRemove	(file) => boolean | Promise<boolean>	—	移除回调；返回 false 阻止
onDrop	(e: DragEvent) => void	—	拖拽放下回调
hint	ReactNode	'Click or drag files to upload'	拖拽区域提示文案
icon	ReactNode	CloudUploadIcon	拖拽区域图标；传 null 隐藏
description	ReactNode	—	补充描述（格式、限制等）
disabled	boolean	false	禁用交互
className	string	—	额外 class

UploadFile

字段	类型	说明
uid	string	唯一标识
name	string	文件名
size	number	文件大小（字节）
status	'uploading' | 'error' | 'done'	上传状态
percent	number	上传进度（0–100）
response	unknown	服务端响应
originFile	File	原始 File 对象