> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/zh/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/zh/llms-full.txt.

# Upload

数据录入`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

选择、拖入并管理文件，支持真实请求、自定义上传和受控列表。

提供 text、picture、picture-card 和 picture-circle 四种列表。下方示例展示本地选择与明确标注的模拟请求；真实上传需通过 `action` 或 `customRequest` 连接自己的服务。

## 代码演示


### 点击选择文件
初始列表展示已完成和失败文件；新选择的文件仅保存在本地，beforeUpload 返回 false 阻止请求。
```tsx preview
import { Upload, Button } from '@rockshin/tao-ui';
export default function Demo() {
  return (
    <Upload
      locale={{
        uploading: '上传中',
        previewFile: '预览文件',
        removeFile: '移除文件',
        downloadFile: '下载文件',
        uploadError: '上传失败',
      }}
      multiple
      beforeUpload={() => false}
      defaultFileList={[
        { uid: '1', name: 'project-brief.pdf', status: 'done' },
        { uid: '2', name: 'requirements.docx', status: 'done' },
        {
          uid: '3',
          name: 'budget.xlsx',
          status: 'error',
          error: new Error('示例：服务器拒绝了此文件'),
        },
      ]}
    >
      <Button>选择文件</Button>
    </Upload>
  );
}
```

### 受控文件列表
通过 onChange 接管 fileList；清空按钮同时更新界面。
```tsx preview
import { Upload, Button, Stack, type UploadFile } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
  const [files, setFiles] = useState<UploadFile[]>([]);
  return (
    <Stack gap="md">
      <Upload
        locale={{
          uploading: '上传中',
          previewFile: '预览文件',
          removeFile: '移除文件',
          downloadFile: '下载文件',
          uploadError: '上传失败',
        }}
        fileList={files}
        beforeUpload={() => false}
        onChange={(info) => setFiles(info.fileList)}
      >
        <Button>选择文件</Button>
      </Upload>
      <Button variant="secondary" onClick={() => setFiles([])}>
        清空列表
      </Button>
    </Stack>
  );
}
```

### 类型校验与忽略
LIST\_IGNORE 阻止不符合要求的文件进入列表；浏览器 accept 仅用于选择提示。
```tsx preview
import { Upload, Button } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
  const [error, setError] = useState('');
  return (
    <div>
      <Upload
        locale={{
          uploading: '上传中',
          previewFile: '预览文件',
          removeFile: '移除文件',
          downloadFile: '下载文件',
          uploadError: '上传失败',
        }}
        accept="image/*"
        beforeUpload={(file) => {
          if (!file.type.startsWith('image/')) {
            setError('请选择图片文件。');
            return Upload.LIST_IGNORE;
          }
          setError('');
          return false;
        }}
      >
        <Button>选择图片</Button>
      </Upload>
      <p role="status">{error}</p>
    </div>
  );
}
```

### 多选与数量限制
maxCount 限制列表长度，1 表示替换当前文件。
```tsx preview
import { Upload, Button, Stack } from '@rockshin/tao-ui';
export default function Demo() {
  return (
    <Stack gap="md">
      <Upload
        locale={{
          uploading: '上传中',
          previewFile: '预览文件',
          removeFile: '移除文件',
          downloadFile: '下载文件',
          uploadError: '上传失败',
        }}
        multiple
        maxCount={3}
        beforeUpload={() => false}
      >
        <Button>最多选择三个文件</Button>
      </Upload>
      <Upload
        locale={{
          uploading: '上传中',
          previewFile: '预览文件',
          removeFile: '移除文件',
          downloadFile: '下载文件',
          uploadError: '上传失败',
        }}
        maxCount={1}
        beforeUpload={() => false}
      >
        <Button variant="secondary">替换单个文件</Button>
      </Upload>
    </Stack>
  );
}
```

### 拖拽上传
点击整个拖拽区域或拖入多个文件。本例仅本地选择，不发送请求。
```tsx preview
import { Upload } from '@rockshin/tao-ui';
export default function Demo() {
  return (
    <Upload.Dragger
      locale={{
        uploading: '上传中',
        previewFile: '预览文件',
        removeFile: '移除文件',
        downloadFile: '下载文件',
        uploadError: '上传失败',
      }}
      multiple
      beforeUpload={() => false}
      height={200}
      hasControlInside={false}
    >
      <svg
        width="48"
        height="48"
        viewBox="0 0 24 24"
        fill="none"
        stroke="currentColor"
        strokeWidth="1.5"
        aria-hidden="true"
        style={{ color: 'var(--tao-primary)' }}
      >
        <path d="M12 16V3m-5 5 5-5 5 5M4 16v5h16v-5" />
      </svg>
      <strong>点击或将文件拖拽到这里</strong>
      <span style={{ color: 'var(--tao-color-text-secondary)' }}>
        支持单个或批量选择文件。
      </span>
    </Upload.Dragger>
  );
}
```

### 图片列表
以紧凑列表展示缩略图、文件名和操作。点击缩略图可预览，新图片仅保存在本地。
```tsx preview
import { Upload, Button } from '@rockshin/tao-ui';
export default function Demo() {
  return (
    <Upload
      locale={{
        uploading: '上传中',
        previewFile: '预览文件',
        removeFile: '移除文件',
        downloadFile: '下载文件',
        uploadError: '上传失败',
      }}
      listType="picture"
      accept="image/*"
      multiple
      beforeUpload={() => false}
      defaultFileList={[
        {
          uid: '1',
          name: 'image-01.png',
          status: 'done',
          url: 'https://rickyshin93.github.io/tao-ui/demos/upload/mountain-lake.png',
        },
        {
          uid: '2',
          name: 'image-02.png',
          status: 'error',
          url: 'https://rickyshin93.github.io/tao-ui/demos/upload/mountain-lake.png',
          error: new Error('示例上传错误'),
        },
      ]}
    >
      <Button>选择图片</Button>
    </Upload>
  );
}
```

### 照片墙与预览
受控 picture-card 列表展示已完成、上传中和失败状态。支持预览与移除，六张图片时隐藏入口。上传进度为初始展示状态，并非运行中的请求。
```tsx preview
import { Upload, Modal, type UploadFile } from '@rockshin/tao-ui';
import { useState } from 'react';
const imageUrl =
  'https://rickyshin93.github.io/tao-ui/demos/upload/mountain-lake.png';
export default function Demo() {
  const [files, setFiles] = useState<UploadFile[]>([
    { uid: '1', name: 'image-01.png', status: 'done', url: imageUrl },
    { uid: '2', name: 'image-02.png', status: 'done', url: imageUrl },
    { uid: '3', name: 'image-03.png', status: 'uploading', percent: 48 },
    {
      uid: '4',
      name: 'image-04.png',
      status: 'error',
      error: new Error('示例上传错误'),
    },
  ]);
  const [preview, setPreview] = useState({ name: '', url: '' });
  const [error, setError] = useState('');
  const showPreview = (file: UploadFile) => {
    setError('');
    if (file.url || file.thumbUrl) {
      setPreview({ name: file.name, url: file.url || file.thumbUrl! });
    } else if (file.originFileObj) {
      const reader = new FileReader();
      reader.onload = () =>
        setPreview({ name: file.name, url: String(reader.result) });
      reader.onerror = () => setError('无法读取此图片。');
      reader.readAsDataURL(file.originFileObj);
    }
  };
  return (
    <>
      <Upload
        locale={{
          uploading: '上传中',
          previewFile: '预览文件',
          removeFile: '移除文件',
          downloadFile: '下载文件',
          uploadError: '上传失败',
        }}
        listType="picture-card"
        hasControlInside={false}
        accept="image/*"
        multiple
        maxCount={6}
        fileList={files}
        beforeUpload={() => false}
        onChange={({ fileList }) => setFiles(fileList)}
        onPreview={showPreview}
        showUploadList={{
          showPreviewIcon: (file) =>
            !!(file.url || file.thumbUrl || file.originFileObj),
        }}
      >
        {files.length >= 6 ? null : (
          <>
            <svg
              width="20"
              height="20"
              viewBox="0 0 24 24"
              fill="none"
              stroke="currentColor"
              strokeWidth="1.8"
              aria-hidden="true"
            >
              <path d="M12 4v16M4 12h16" />
            </svg>
            <span>添加图片</span>
          </>
        )}
      </Upload>
      {error && <p role="alert">{error}</p>}
      <Modal
        open={!!preview.url}
        title={preview.name}
        footer={null}
        onClose={() => setPreview({ name: '', url: '' })}
      >
        <img
          src={preview.url || undefined}
          alt={preview.name}
          style={{ display: 'block', width: '100%' }}
        />
      </Modal>
    </>
  );
}
```

### 圆形图片列表
文件卡片与上传入口均为圆形。键盘聚焦与鼠标悬停均可显示操作。
```tsx preview
import { Upload } from '@rockshin/tao-ui';
export default function Demo() {
  return (
    <Upload
      locale={{
        uploading: '上传中',
        previewFile: '预览文件',
        removeFile: '移除文件',
        downloadFile: '下载文件',
        uploadError: '上传失败',
      }}
      listType="picture-circle"
      accept="image/*"
      beforeUpload={() => false}
      defaultFileList={[
        {
          uid: '1',
          name: 'profile.png',
          status: 'done',
          url: 'https://rickyshin93.github.io/tao-ui/demos/upload/mountain-lake.png',
        },
      ]}
      hasControlInside={false}
    >
      <svg
        width="20"
        height="20"
        viewBox="0 0 24 24"
        fill="none"
        stroke="currentColor"
        strokeWidth="1.8"
        aria-hidden="true"
      >
        <path d="M12 4v16M4 12h16" />
      </svg>
      <span>添加图片</span>
    </Upload>
  );
}
```

### 头像选择
隐藏文件列表并替换单张图片。生成本地预览前校验图片类型和 2 MB 大小限制；本例不会向服务器保存头像。
```tsx preview
import { Upload } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
  const [avatar, setAvatar] = useState('');
  const [error, setError] = useState('');
  return (
    <>
      <Upload
        locale={{
          uploading: '上传中',
          previewFile: '预览文件',
          removeFile: '移除文件',
          downloadFile: '下载文件',
          uploadError: '上传失败',
        }}
        listType="picture-circle"
        showUploadList={false}
        accept="image/*"
        maxCount={1}
        hasControlInside={false}
        beforeUpload={(file) => {
          if (!file.type.startsWith('image/') || file.size > 2 * 1024 * 1024) {
            setError('请选择小于 2 MB 的图片。');
            return Upload.LIST_IGNORE;
          }
          setError('');
          const reader = new FileReader();
          reader.onload = () => setAvatar(String(reader.result));
          reader.onerror = () => setError('无法读取此图片。');
          reader.readAsDataURL(file);
          return false;
        }}
      >
        {avatar ? (
          <img
            src={avatar}
            alt="已选择的头像"
            style={{
              width: '100%',
              height: '100%',
              borderRadius: '50%',
              objectFit: 'cover',
            }}
          />
        ) : (
          <span>选择头像</span>
        )}
      </Upload>
      {error && <p role="alert">{error}</p>}
    </>
  );
}
```

### 自定义请求与进度
此处为不访问网络的明确模拟：选择文件可观察进度、完成与取消。打开开关可模拟失败。实际项目请将 customRequest 替换为真实请求。
```tsx preview
import { Upload, Button, Switch, type UploadProps } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
  const [fail, setFail] = useState(false);
  const customRequest: UploadProps['customRequest'] = ({
    onProgress,
    onSuccess,
    onError,
  }) => {
    let percent = 0;
    const timer = window.setInterval(() => {
      percent += 20;
      onProgress?.({ percent });
      if (percent === 100) {
        window.clearInterval(timer);
        if (fail) onError?.(new Error('模拟上传失败'));
        else onSuccess?.({ simulated: true });
      }
    }, 300);
    return { abort: () => window.clearInterval(timer) };
  };
  return (
    <div style={{ display: 'grid', gap: 16 }}>
      <label>
        <Switch checked={fail} onChange={setFail} /> 模拟失败
      </label>
      <Upload
        locale={{
          uploading: '上传中',
          previewFile: '预览文件',
          removeFile: '移除文件',
          downloadFile: '下载文件',
          uploadError: '上传失败',
        }}
        multiple
        customRequest={customRequest}
        progress={{ showInfo: true }}
      >
        <Button>开始模拟上传</Button>
      </Upload>
    </div>
  );
}
```

### 禁用状态
禁用选择和移除，保留已完成文件的预览能力。
```tsx preview
import { Upload, Switch } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
  const [disabled, setDisabled] = useState(true);
  return (
    <div style={{ display: 'grid', gap: 16 }}>
      <label>
        <Switch checked={disabled} onChange={setDisabled} /> 禁用
      </label>
      <Upload
        locale={{
          uploading: '上传中',
          previewFile: '预览文件',
          removeFile: '移除文件',
          downloadFile: '下载文件',
          uploadError: '上传失败',
        }}
        disabled={disabled}
        listType="picture-card"
        beforeUpload={() => false}
        defaultFileList={[
          {
            uid: '1',
            name: 'image.png',
            status: 'done',
            url: 'https://rickyshin93.github.io/tao-ui/demos/upload/mountain-lake.png',
          },
        ]}
        hasControlInside={false}
      >
        <svg
          width="20"
          height="20"
          viewBox="0 0 24 24"
          fill="none"
          stroke="currentColor"
          strokeWidth="1.8"
          aria-hidden="true"
        >
          <path d="M12 4v16M4 12h16" />
        </svg>
        <span>添加图片</span>
      </Upload>
    </div>
  );
}
```

### 确认移除
onRemove 可同步或异步拒绝移除；示例通过开关控制保留文件。
```tsx preview
import { Upload, Button, Switch } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
  const [locked, setLocked] = useState(true);
  return (
    <div>
      <label>
        <Switch checked={locked} onChange={setLocked} /> 保护文件
      </label>
      <Upload
        locale={{
          uploading: '上传中',
          previewFile: '预览文件',
          removeFile: '移除文件',
          downloadFile: '下载文件',
          uploadError: '上传失败',
        }}
        beforeUpload={() => false}
        onRemove={() => !locked}
        defaultFileList={[
          { uid: '1', name: 'protected-report.pdf', status: 'done' },
        ]}
      >
        <Button>选择文件</Button>
      </Upload>
    </div>
  );
}
```

### 列表补充信息
按文件渲染额外说明，并控制预览、下载和移除操作。
```tsx preview
import { Upload, Button } from '@rockshin/tao-ui';
export default function Demo() {
  return (
    <Upload
      locale={{
        uploading: '上传中',
        previewFile: '预览文件',
        removeFile: '移除文件',
        downloadFile: '下载文件',
        uploadError: '上传失败',
      }}
      beforeUpload={() => false}
      defaultFileList={[
        { uid: '1', name: 'design-notes.pdf', size: 245760, status: 'done' },
      ]}
      showUploadList={{
        extra: (file) => (
          <small>{Math.ceil((file.size ?? 0) / 1024)} KB · 本地文件</small>
        ),
        showDownloadIcon: false,
      }}
    >
      <Button>选择文档</Button>
    </Upload>
  );
}
```

### 手机选择与粘贴
pastable 支持剪贴板文件；浏览器和设备决定可用的选择来源。
```tsx preview="iframe-follow"
import { Upload, Button } from '@rockshin/tao-ui';
export default function Demo() {
  return (
    <Upload
      locale={{
        uploading: '上传中',
        previewFile: '预览文件',
        removeFile: '移除文件',
        downloadFile: '下载文件',
        uploadError: '上传失败',
      }}
      pastable
      multiple
      beforeUpload={() => false}
      listType="picture"
    >
      <Button>选择或粘贴图片</Button>
    </Upload>
  );
}
```

## API

| 属性                                  | 类型                                                       | 默认值             | 说明                                                           |
| ----------------------------------- | -------------------------------------------------------- | --------------- | ------------------------------------------------------------ |
| `fileList / defaultFileList`        | `UploadFile[]`                                           | —               | 受控文件列表 / 非受控初始列表。                                            |
| `onChange`                          | `({ file, fileList, event? }) => void`                   | —               | 选择、进度、完成、失败与移除时回调。                                           |
| `action`                            | `string or (file) => string / PromiseLike<string>`       | —               | 上传地址；默认请求需要提供此项。                                             |
| `customRequest`                     | `(options, { defaultRequest }) => void / { abort() }`    | —               | 接管请求，通过 options 回调报告进度、成功或失败。                                |
| `beforeUpload`                      | `(file, files) => boolean / File / Blob / Promise`       | —               | false 阻止请求但保留列表项；Upload.LIST\_IGNORE 忽略文件；返回 File/Blob 转换文件。 |
| `listType`                          | `'text' / 'picture' / 'picture-card' / 'picture-circle'` | 'text'          | 列表类型；卡片与圆形模式的选择入口排在文件后。                                      |
| `showUploadList`                    | `boolean or ShowUploadListInterface`                     | true            | 设置列表可见性、补充内容，以及每个文件的预览、下载、移除操作。                              |
| `maxCount`                          | `number`                                                 | —               | 限制数量；1 表示替换已有文件。通过 children={null} 自行隐藏入口。                   |
| `multiple / directory / pastable`   | `boolean`                                                | false           | 多选 / 目录选择 / 接收剪贴板文件。                                         |
| `accept`                            | `string or AcceptConfig`                                 | —               | 文件选择提示，如 image/\*；请在 beforeUpload 中校验文件。                     |
| `capture`                           | `boolean / 'user' / 'environment'`                       | —               | 向原生文件选择器传递拍摄提示。                                              |
| `name / method`                     | `string`                                                 | 'file' / 'post' | 文件字段名与 HTTP 方法（POST、PUT 或 PATCH）。                            |
| `data`                              | `object or (file) => object / Promise<object>`           | —               | 附加 multipart 字段。                                             |
| `headers / withCredentials`         | `object / boolean`                                       | — / false       | 请求头与是否携带凭据。                                                  |
| `onPreview / onDownload`            | `(file) => void`                                         | —               | 接管预览/下载；下载操作仅针对 done 文件，本地图片支持内置预览。                          |
| `onRemove`                          | `(file) => void / boolean / Promise`                     | —               | 返回 false（或 Promise 解析为 false）阻止移除；允许移除时中止正在进行的请求。            |
| `previewFile`                       | `(file: File or Blob) => PromiseLike<string>`            | —               | 生成本地缩略图 URL。                                                 |
| `isImageUrl / iconRender`           | `(file) => boolean / (file, listType) => ReactNode`      | —               | 自定义图片识别、文件与上传中图标。                                            |
| `itemRender`                        | `(node, file, fileList, actions) => ReactNode`           | —               | 自定义文件项，actions 提供 preview、download、remove。                   |
| `progress`                          | `UploadListProgressProps`                                | —               | 配置上传进度条。                                                     |
| `disabled`                          | `boolean`                                                | TaoProvider     | 禁用选择与移除，仍可预览。                                                |
| `openFileDialogOnClick`             | `boolean`                                                | true            | 激活入口时打开文件选择器。                                                |
| `hasControlInside`                  | `boolean`                                                | Automatic / 自动  | 纯文本或非交互自定义内容设为 false，使外层入口可通过键盘操作。                           |
| `onDrop / onFocus`                  | `event handler`                                          | —               | 接收拖放与聚焦事件。                                                   |
| `locale`                            | `UploadLocale`                                           | TaoProvider     | 覆盖上传中、预览、下载、移除和错误文案。                                         |
| `classNames / styles`               | `object or ({ props }) => object`                        | —               | 语义部件：root、trigger、list、item。                                 |
| `className / rootClassName / style` | `string / string / CSSProperties`                        | —               | 根节点样式；Dragger 的 style 作用于拖拽区域。                               |
| `id / children`                     | `string / ReactNode`                                     | —               | 输入框标识与选择入口内容；null 或 false 隐藏入口。                              |

### Upload.Dragger

继承 Upload 属性，额外提供 `height?: number` 设置拖拽区域高度，不包含文件列表。

### UploadFile

必填 `uid`、`name`；常用字段包括 `status`（uploading / done / error / removed）、`percent`、`url`、`thumbUrl`、`originFileObj`、`response`、`error`、`size` 与 `type`。被 beforeUpload 阻止的本地文件没有 status。

### ShowUploadListInterface

`showPreviewIcon`、`showDownloadIcon`、`showRemoveIcon` 支持布尔值或 `(file) => boolean`；`previewIcon`、`downloadIcon`、`removeIcon`、`extra` 支持 ReactNode 或 `(file) => ReactNode`。图片卡片默认显示预览与移除；下载默认隐藏。

## 连接上传服务

官网示例仅本地选择或模拟请求。接入服务端时，将 `action` 设为上传接口地址，`name` 设为服务端接收文件的 multipart 字段名。

```tsx
import { Upload, Button } from '@rockshin/tao-ui';

// The application must implement this endpoint.
export function ServerUpload() {
  return (
    <Upload
      locale={{
        uploading: '上传中',
        previewFile: '预览文件',
        removeFile: '移除文件',
        downloadFile: '下载文件',
        uploadError: '上传失败',
      }}
      action="/api/uploads"
      name="file"
      data={{ folder: 'documents' }}
    >
      <Button>Upload to server</Button>
    </Upload>
  );
}
```

使用 `customRequest` 时，通过 `onProgress` 报告进度，每次请求结束时调用一次 `onSuccess` 或 `onError`。如果请求支持取消，返回带有 `abort()` 方法的对象。使用受控 `fileList` 时，把 `onChange` 传回的文件列表保存到状态，以显示每个文件的最新状态。

从 [0.0.49](https://rickyshin93.github.io/tao-ui/zh/guide/changelog.md) 起，组件还会处理解析 `action` 或 `data` 时的失败，以及 `customRequest` 同步抛出的异常。出错文件显示失败状态，同批其他文件继续上传。
