# 上传 Upload

- 页面: https://jiguang132.com/zh/resources/arco-design/docs/upload
- 资源: Arco Design (https://jiguang132.com/zh/resources/arco-design.md)
- 全部指南: https://jiguang132.com/zh/resources/arco-design/docs.md

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

## 安装

```bash
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

|参数名|描述|类型|默认值|版本|
|---|---|---|---|---|
|autoUpload|是否选中文件后自动上传|boolean |`true`|-|
|directory|文件夹上传|boolean |`-`|2.11.0|
|disabled|禁用|boolean |`-`|-|
|drag|是否拖拽上传|boolean |`-`|-|
|imagePreview|启用内置的图片预览，仅在 listType='picture-card' 时生效。(`v2.41.0`)|boolean |`-`|-|
|multiple|文件多选|boolean |`-`|-|
|withCredentials|上传请求是否携带 cookie|boolean |`-`|-|
|action|上传接口地址|string |`-`|-|
|method|上传请求的 http method|string |`post`|2.55.0|
|listType|展示类型|'text' \| 'picture-list' \| 'picture-card' |`text`|-|
|tip|提示文字，listType 不同，展示会有区别|string \| React.ReactNode |`-`|-|
|accept|接受上传的类型 [详细请参考](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept)。（`strict` in `2.53.0`，默认为 true。设置为 false 时，accept 表现和原生一致。设置为 true 时，会严格匹配文件后缀名，过滤掉不符合 accept 规则的文件。)|string \| { type: string; strict?: boolean } |`-`|-|
|beforeUpload|上传文件之前的回调。返回 false 或者 promise抛出异常的时候会取消上传。|(file: File, filesList: File[]) =&gt; boolean \| Promise&lt;any&gt; |`() => true`|-|
|className|节点类名|string \| string[] |`-`|-|
|defaultFileList|默认已上传的文件列表|[UploadItem](upload#uploaditem)[] |`-`|-|
|fileList|已上传的文件列表|[UploadItem](upload#uploaditem)[] |`-`|-|
|headers|上传时使用的 headers|object |`-`|-|
|limit|限制上传数量。默认超出后会隐藏上传节点。对象类型在 `2.28.0` 支持|number \| { maxCount: number; hideOnExceedLimit?: boolean } |`-`|-|
|onRemove|点击删除文件时的回调。返回 `false` 或者 `Promise.reject` 的时候不会执行删除。|(file: [UploadItem](upload#uploaditem), fileList: [UploadItem](upload#uploaditem)[]) =&gt; void \| boolean \| Promise&lt;void \| boolean&gt; |`-`|-|
|progressProps|进度条属性，接收所有进度条的 props。|Partial&lt;[ProgressProps](progress#progress)&gt; |`-`|-|
|showUploadList|是否展示上传文件列表。预览图标，删除图标，文件图标，重新上传图标，取消上传图标。|boolean \| [CustomIconType](#customicontype) |`true`|-|
|style|节点样式|CSSProperties |`-`|-|
|customRequest|通过覆盖默认的上传行为，可以自定义自己的上传实现|(options: [RequestOptions](#requestoptions)) => [UploadRequestReturn](#uploadrequestreturn) \| void |`-`|-|
|data|上传时的 Body 参数|object \| ((any: any) => object) |`-`|-|
|name|发请求时文件内容的参数名|string \| ((any: any) => string) |`-`|-|
|onChange|上传文件改变时的回调。文件开始上传，失败，成功时会触发。注意：如果需要实时获取文件的上传进度，请在 `onProgress` 中处理。|(fileList: [UploadItem](upload#uploaditem)[], file: [UploadItem](upload#uploaditem)) => void |`-`|-|
|onDragLeave|拖拽上传文件离开拖拽区时的回调|(e: React.DragEvent) => void |`-`|2.41.0|
|onDragOver|拖拽上传文件进入拖拽区时的回调|(e: React.DragEvent) => void |`-`|2.41.0|
|onDrop|拖拽上传文件时执行的回调|(e: React.DragEvent) => void |`-`|2.37.0|
|onExceedLimit|超出上传数量限制时触发|(files: File[], fileList: [UploadItem](upload#uploaditem)[]) => void |`-`|-|
|onPreview|点击预览时候的回调|(file: [UploadItem](upload#uploaditem)) => void |`-`|-|
|onProgress|文件上传进度的回调|(file: [UploadItem](upload#uploaditem), e?: ProgressEvent) => void |`-`|-|
|onReupload|文件重新上传时触发的回调|(file: [UploadItem](upload#uploaditem)) => void |`-`|-|
|renderUploadItem|自定义上传列表项|(originNode: ReactNode, file: [UploadItem](upload#uploaditem), fileList: [UploadItem](upload#uploaditem)[]) => ReactNode |`-`|-|
|renderUploadList|自定义展示上传文件列表|(fileList: [UploadItem](upload#uploaditem)[], uploadListProps: [UploadListProps](upload#uploadlistprops)) => ReactNode |`-`|-|

### UploadListProps

文件上传列表展示

|参数名|描述|类型|默认值|
|---|---|---|---|
|disabled|禁用|boolean |`-`|
|onRemove|点击删除文件时的回调。返回 false 或者 Promise.reject 的时候不会执行删除|(file: [UploadItem](upload#uploaditem)) =&gt; void \| boolean \| Promise&lt;void \| boolean&gt; |`-`|
|onAbort|中止文件上传的回调|(file: [UploadItem](upload#uploaditem)) => void |`-`|
|onPreview|点击预览时候的回调。|(file: [UploadItem](upload#uploaditem)) => void |`-`|
|onReupload|重新上传的回调|(file: [UploadItem](upload#uploaditem)) => void |`-`|

### UploadItem

|参数名|描述|类型|默认值|
|---|---|---|---|
|percent|上传进度百分比|number |`-`|
|name|文件名|string |`-`|
|uid|当前上传文件的唯一标示|string  **(必填)**|`-`|
|url|文件 url|string |`-`|
|originFile|文件对象|File |`-`|
|response|当前文件上传请求返回的响应|object |`-`|
|status|当前上传文件的状态|[UploadStatus](#uploadstatus) |`-`|

### RequestOptions

```js
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

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

### CustomIconType

```js
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

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

### 方法/Methods

| 参数名     |                                  描述                                   |                         类型                        |
| ---------- | :---------------------------------------------------------------------: | :--------------------------------------------------: |
| submit   | 手动上传时，调用该方法，开始上传。[示例](/react/components/upload#手动上传)。不传参数时，会默认上传全部`init`状态的文件。  | `(file?: UploadItem) => void` |
| abort   | 中止文件上传 | `(file: UploadItem) => void` |
| reupload   | 重新上传文件 | `(file: UploadItem) => void` |

```js
// 自定义图标类型
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
}
```

## 常见问题

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

可以参考 [示例](https://codepen.io/yinkaihui/pen/NWGmGRB?editors=0010) ，，建议设置 `autoUpload`为 `false`。并通过 `fileList` 和 `onChange` 使组件完全受控。
`fileList `是`UploadItem[]`，可以直接设置元素的 `status`，`percent `等字段。

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt