上传 Upload

用户可传输文件或提交相应的内容。

安装

npm install @arco-design/web-react@2.66.18

在入口引入 @arco-design/web-react/dist/css/arco.css，用 ConfigProvider 设置语言。React 19 项目还需在入口最先引入 @arco-design/web-react/es/_util/react-19-adapter，否则 Message、Modal 等命令式 API 无法渲染。

示例

• 基础用法：最基础的上传组件用法。
• 用户头像上传：点击上传用户头像，可使用 beforeUpload 限制用户上传的图片格式和大小。
• 已上传的文件列表：默认的文件上传列表
• 照片墙：点击图片预览按钮时，可以onPreview中进行预览逻辑。 可以通过 imagePreview 属性启用内置的图片预览。（imagePreview 属性在 2.41.0 支持）
• 拖拽上传：拖拽上传。当使用拖拽上传，且设置 accept 时候，选择后的文件将会被根据后缀名及文件类型被过滤。不符合格式的文件将不会出现在上传列表。
• 图片列表样式：图片列表样式
• 手动上传：设置 autoUpload 为 false时候，可以通过调用 submit方法进行手动上传。submit 只会上传处于 fileList 中的文件。
• 上传前校验：beforeUpload 会在每一个文件上传之前执行。如果返回 false 或者 Promise.reject， 那么将会取消当前文件的上传。
• 上传前裁剪：beforeUpload 会在每一个文件上传之前执行。如果返回 false 或者 Promise.reject， 那么将会取消当前文件的上传。
• 移除前校验：onRemove 会在每个文件从上传列表中删除之前执行。如果返回 false 或者 Promise.reject，那么将会终止移除操作。
• 限制上传数量：通过limit限制上传的最大数量。超出后上传按钮会隐藏.
• 自定义上传节点：可以传入自定义内容作为文件上传的触发节点。
• 自定义图标：showUploadList 字段可以设置图标。
• 自定义文件上传列表展示：传入 renderUploadList 可以自定义展示文件上传列表。第一个参数是当前上传列表，第二个参数是上传列表相关的属性。详细可参考 <UploadListProps>
• 自定义上传实现：默认通过 Ajax 请求上传，可以设置 customRequest 覆盖默认的上传请求，实现自定义上传。 返回值是一个对象，包含 abort 用来终止上传。
• 自定义进度条：progressProps 字段可以自定义进度条属性。
• 文件夹上传：文件夹上传

示例来自 Arco Design 官方仓库（MIT），固定在 npm 2.66.18 对应的提交；部分示例使用在线图片或上传地址，预览中网络请求被禁用。

API

Upload

UploadListProps

文件上传列表展示

UploadItem

RequestOptions

export type RequestOptions = Pick<
  UploadProps,
  "headers" | "name" | "data" | "withCredentials" | "action" | "method"
> & {
  /** 更新当前文件的上传进度 。percent: 当前上传进度百分比 */
  onProgress: (percent: number, event?: ProgressEvent) => void;
  /** 上传成功后，调用onSuccess方法，传入的response参数将会附加到当前上传文件的reponse字段上 */
  onSuccess: (response?: object) => void;
  /** 上传失败后，调用onError方法，传入的 response 参数将会附加到当前上传文件的response字段 */
  onError: (response?: object) => void;
  /** 当前上传文件 */
  file: File;
};

UploadRequestReturn

export interface UploadRequestReturn {
  abort?: () => void;
  [key: string]: any;
}

CustomIconType

export type CustomIconType = {
  previewIcon?: ReactNode;
  removeIcon?: ReactNode;
  fileIcon?: ReactNode;
  reuploadIcon?: ReactNode;
  cancelIcon?: ReactNode;
  startIcon?: ReactNode;
  errorIcon?: ReactNode;
  successIcon?: ReactNode;
  fileName?: (file: UploadItem) => ReactNode;
  // 2.34.0
  progressRender?: (
    file: UploadItem,
    originDom: ReactNode
  ) => React.ReactElement;
  // 2.34.0
  imageRender?: (file: UploadItem) => React.ReactNode;
};

UploadStatus

export type UploadStatus = "init" | "uploading" | "done" | "error";

方法/Methods

// 自定义图标类型
type CustomIconType = {
  previewIcon?: ReactNode;
  removeIcon?: ReactNode;
  fileIcon?: ReactNode;
  reuploadIcon?: ReactNode;
  cancelIcon?: ReactNode;
  startIcon?: ReactNode;
  errorIcon?: ReactNode;
  fileName?: (file: UploadItem) => ReactNode;
  progressRender?: (file: UploadItem, originDom: ReactNode) => ReactElement; // 2.34.0
  imageRender?: (file: UploadItem) => ReactNode; // 2.34.0
}

常见问题

如何完全控制上传文件的状态和进度？

可以参考 示例 ，，建议设置 autoUpload为 false。并通过 fileList 和 onChange 使组件完全受控。 fileList 是UploadItem[]，可以直接设置元素的 status，percent 等字段。