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, and this page is available as Markdown at https://rickyshin93.github.io/tao-ui/zh/components/upload.md.
v0.0.57
  • 简体中文
  • Upload

    数据录入@rockshin/tao-ui

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

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

    代码演示

    点击选择文件

    初始列表展示已完成和失败文件;新选择的文件仅保存在本地,beforeUpload 返回 false 阻止请求。

    project-brief.pdfrequirements.docxbudget.xlsx示例:服务器拒绝了此文件
    TSX

    受控文件列表

    通过 onChange 接管 fileList;清空按钮同时更新界面。

    TSX

    类型校验与忽略

    LIST_IGNORE 阻止不符合要求的文件进入列表;浏览器 accept 仅用于选择提示。

    TSX

    多选与数量限制

    maxCount 限制列表长度,1 表示替换当前文件。

    TSX

    拖拽上传

    点击整个拖拽区域或拖入多个文件。本例仅本地选择,不发送请求。

    点击或将文件拖拽到这里支持单个或批量选择文件。
    TSX

    图片列表

    以紧凑列表展示缩略图、文件名和操作。点击缩略图可预览,新图片仅保存在本地。

    image-01.pngimage-02.png示例上传错误
    TSX

    照片墙与预览

    受控 picture-card 列表展示已完成、上传中和失败状态。支持预览与移除,六张图片时隐藏入口。上传进度为初始展示状态,并非运行中的请求。

    image-01.pngimage-02.png上传中
    示例上传错误添加图片
    TSX

    圆形图片列表

    文件卡片与上传入口均为圆形。键盘聚焦与鼠标悬停均可显示操作。

    profile.png添加图片
    TSX

    头像选择

    隐藏文件列表并替换单张图片。生成本地预览前校验图片类型和 2 MB 大小限制;本例不会向服务器保存头像。

    选择头像
    TSX

    自定义请求与进度

    此处为不访问网络的明确模拟:选择文件可观察进度、完成与取消。打开开关可模拟失败。实际项目请将 customRequest 替换为真实请求。

    TSX

    禁用状态

    禁用选择和移除,保留已完成文件的预览能力。

    image.png添加图片
    TSX

    确认移除

    onRemove 可同步或异步拒绝移除;示例通过开关控制保留文件。

    protected-report.pdf
    TSX

    列表补充信息

    按文件渲染额外说明,并控制预览、下载和移除操作。

    design-notes.pdf240 KB · 本地文件
    TSX

    手机选择与粘贴

    pastable 支持剪贴板文件;浏览器和设备决定可用的选择来源。

    390 × 640
    TSX

    API

    属性类型默认值说明
    fileList / defaultFileListUploadFile[]—受控文件列表 / 非受控初始列表。
    onChange({ file, fileList, event? }) => void—选择、进度、完成、失败与移除时回调。
    actionstring 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'列表类型;卡片与圆形模式的选择入口排在文件后。
    showUploadListboolean or ShowUploadListInterfacetrue设置列表可见性、补充内容,以及每个文件的预览、下载、移除操作。
    maxCountnumber—限制数量;1 表示替换已有文件。通过 children= 自行隐藏入口。
    multiple / directory / pastablebooleanfalse多选 / 目录选择 / 接收剪贴板文件。
    acceptstring or AcceptConfig—文件选择提示,如 image/*;请在 beforeUpload 中校验文件。
    captureboolean / 'user' / 'environment'—向原生文件选择器传递拍摄提示。
    name / methodstring'file' / 'post'文件字段名与 HTTP 方法(POST、PUT 或 PATCH)。
    dataobject or (file) => object / Promise<object>—附加 multipart 字段。
    headers / withCredentialsobject / 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。
    progressUploadListProgressProps—配置上传进度条。
    disabledbooleanTaoProvider禁用选择与移除,仍可预览。
    openFileDialogOnClickbooleantrue激活入口时打开文件选择器。
    hasControlInsidebooleanAutomatic / 自动纯文本或非交互自定义内容设为 false,使外层入口可通过键盘操作。
    onDrop / onFocusevent handler—接收拖放与聚焦事件。
    localeUploadLocaleTaoProvider覆盖上传中、预览、下载、移除和错误文案。
    classNames / stylesobject or ({ props }) => object—语义部件:root、trigger、list、item。
    className / rootClassName / stylestring / string / CSSProperties—根节点样式;Dragger 的 style 作用于拖拽区域。
    id / childrenstring / 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 字段名。

    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 起,组件还会处理解析 action 或 data 时的失败,以及 customRequest 同步抛出的异常。出错文件显示失败状态,同批其他文件继续上传。