上传

文件选择上传和拖拽上传控件。

何时使用

上传是将信息（网页、文字、图片、视频等）通过网页或者上传工具发布到远程服务器上的过程。

• 当需要上传一个或一些文件时。
• 当需要展现上传的进度时。
• 当需要使用拖拽交互时。

代码演示

• 点击上传 · basic

• 用户头像 · avatar

• 已上传的文件列表 · defaultFileList

• 照片墙 · picture-card

• 圆形照片墙 · picture-circle

• 完全控制的上传列表 · fileList

• 拖拽上传 · drag

• 粘贴上传 · paste

• 文件夹上传 · directory

• 手动上传 · upload-manually

• 只上传 png 图片 · upload-png-only

• 图片列表样式 · picture-style

• 自定义预览 · preview-file

• 限制数量 · max-count

• 上传前转换文件 · transform-file

• 阿里云 OSS · upload-with-aliyun-oss

• 自定义交互图标和文件信息 · upload-custom-action-icon

• 上传列表拖拽排序 · drag-sorting

• 上传前裁切图片 · crop-image

• 自定义进度条样式 · customize-progress-bar

• 自定义语义结构的样式和类 · style-class

API

通用属性参考：通用属性

Interface

RcFile

继承自 File。

UploadFile

继承自 File，附带额外属性用于渲染。

RequestOptions

onChange

💡 上传中、完成、失败都会调用这个函数。

文件状态改变的回调，返回为：

{
  file: { /* ... */ },
  fileList: [ /* ... */ ],
  event: { /* ... */ },
}

1. file 当前操作的文件对象。

   {
      uid: 'uid',      // 文件唯一标识，建议设置为负数，防止和内部产生的 id 冲突
      name: 'xx.png',   // 文件名
      status: 'done' | 'uploading' | 'error' | 'removed' , //  beforeUpload 拦截的文件没有 status 状态属性
      response: '{"status": "success"}', // 服务端响应内容
      linkProps: '{"download": "image"}', // 下载链接额外的 HTML 属性
   }
   

2. fileList 当前的文件列表。

3. event 上传中的服务端响应内容，包含了上传进度等信息，高级浏览器支持。

AcceptObject

{
  format: string;
  filter?: 'native' | ((file: RcFile) => boolean);
}

用于配置文件类型接受的规则对象。

Semantic DOM

语义说明来源: vendor/components/upload/demo/_semantic.tsx

主题变量（Design Token）

类型、继承关系和原生令牌声明保持固定源码原文；默认值由原生主题计算，并可能受 ConfigProvider 覆盖。本表不伪造静态默认值。

声明来源: vendor/components/upload/style/index.ts

import type { CSSObject } from '@ant-design/cssinjs';

import { resetComponent } from '../../style';

import { genCollapseMotion } from '../../style/motion';

import type { FullToken, GenerateStyle, GetDefaultToken } from '../../theme/internal';

import { genStyleHooks, mergeToken } from '../../theme/internal';

import genDraggerStyle from './dragger';

import genListStyle from './list';

import genMotionStyle from './motion';

import { genPictureCardStyle, genPictureStyle } from './picture';

import genRtlStyle from './rtl';

export interface ComponentToken {
  /**
   * @desc 操作按扭颜色
   * @descEN Action button color
   */
  actionsColor: string;
  /**
   * @desc 卡片类型文件列表项的尺寸（对 picture-card 和 picture-circle 生效）
   * @descEN Size of list items in card type (affects both picture-card and picture-circle)
   */
  pictureCardSize: number;
}

export interface UploadToken extends FullToken<'Upload'> {
  uploadThumbnailSize: number | string;
  uploadProgressOffset: number | string;
  uploadPicCardSize: number | string;
}

FAQ

服务端如何实现？

• 服务端上传接口实现可以参考 jQuery-File-Upload。
• 如果要做本地 mock 可以参考这个 express 的例子。

如何显示下载链接？

请使用 fileList 属性设置数组项的 url 属性进行展示控制。

customRequest 怎么使用？

请参考 https://github.com/react-component/upload#customrequest。

为何 fileList 受控时，上传不在列表中的文件不会触发 onChange 后续的 status 更新事件？

onChange 事件仅会作用于在列表中的文件，因而 fileList 不存在对应文件时后续事件会被忽略。请注意，在 4.13.0 版本之前受控状态存在 bug 导致不在列表中的文件也会触发。

onChange 为什么有时候返回 File 有时候返回 { originFileObj: File }？

历史原因，在 beforeUpload 返回 false 时，会返回 File 对象。在下个大版本我们会统一返回 { originFileObj: File } 对象。当前版本已经兼容所有场景下 info.file.originFileObj 获取原 File 写法。你可以提前切换。

为何有时 Chrome 点击 Upload 无法弹出文件选择框？

与 antd 无关，原生上传也会失败。请重启 Chrome 浏览器，让其完成升级工作。

相关 issue：

• #48007
• #32672
• #32913
• #33988

文件夹上传在 Safari 仍然可以选中文件?

组件内部是以 directory、webkitdirectory 属性控制 input 来实现文件夹选择的, 但似乎在 Safari 的实现中，并不会阻止用户选择文件。可以通过 accept 配置来解决此问题，例如：

accept = {
  // 不允许选择任何文件
  format: `.${'n'.repeat(100)}`,
  // 当选择文件夹后，接受所有文件夹内的文件
  filter: () => true,
};

原生通用属性

Tips: 以下通用属性适用于 antd 大部分组件，不支持的组件会单独说明。

安装并复现示例

npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23

使用 ConfigProvider 和原生 App，并单独配置 dayjs 语言。每个示例在查看代码中列出完整源码文件和额外固定依赖。示例名称用于选择演示，不是组件通用属性。主题、语言与 SSR 初始化见资源安装指南。

原生类型参考

源码查看器包含未修改的原生实现和以下声明文件，继承类型仍位于原生包中。代码中的英文注释保留为源码参考。

• vendor/components/upload/Dragger.tsx
• vendor/components/upload/Upload.tsx
• vendor/components/upload/UploadList/ListItem.tsx
• vendor/components/upload/UploadList/index.tsx
• vendor/components/upload/index.tsx
• vendor/components/upload/interface.ts
• vendor/components/upload/style/index.ts

来源与许可

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

保留原生中英文正文与可执行示例；官网专用的嵌入章节和令牌表格在本地展开。Ant Design 使用 MIT 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。

本地示例适配

• authored/demos/upload/crop-image.tsx: 按 ConfigProvider 的语言显式设置原生裁剪器标题、重置与操作文案，不依赖浏览器语言。 原始对照文件: vendor/components/upload/demo/crop-image.tsx.
• authored/demos/upload/preview-file.tsx: 缩略图服务不可用或响应无效时，显示原生警告并回退到无缩略图，不误报上传成功。 原始对照文件: vendor/components/upload/demo/preview-file.tsx.
• authored/demos/upload/drag-sorting.tsx: 忽略上传列表外的拖放和已不存在的文件标识，避免把无效负索引传给 arrayMove 导致误排序。 原始对照文件: vendor/components/upload/demo/drag-sorting.tsx.

复制示例清单中的适配 sourceFiles；上游对照源码保持不变。详见 LOCAL_CHANGES.md。