• Loading

    Upload 上传组件

    何时使用

    用户根据提示将自己本地的相应信息(包含本地和云储存)上传到网站，上传组件可以帮助用户对上传过程和上传结果有预期，并可以更改或撤销上传行为。

    基本用法

    文件上传

    Loading demo...

    提醒: //upload-server.alibaba.net/upload.do接口: 该接口仅作为测试使用,业务请勿使用 该接口仅支持图片上传,其他文件类型接口请自备

    接口返回数据格式要求

    {
  "success": true,
  "message": "上传成功",                                  // success=false 时候可以返回错误信息
  "url": "http://kfupload.alibaba.com/a.png"             // 返回结果
  "imgURL": "http://kfupload.alibaba.com/a.png",         // 图片预览地址 (非必须)
  "downloadURL": "http://kfupload.alibaba.com/a.png",    // 文件下载地址 (非必须)
}

    后端数据格式化

    通过 formatter 将来自后端的 不规则数据 转换为 符合组件要求 的数据格式

    假设服务器的响应数据如下

    {
  "status": "success",                              // 上传成功返回码
  "img_src": "http://kfupload.alibaba.com/a.jpg",   // 图片链接
}

    使用 formatter 对接口返回的不规则数据进行转换

    <Upload
  action="http://127.0.0.1:3001/upload"
  formatter={(res) => {
    return {
      success: res.status === 'success',
      url: res.img_src,
    }
  }}
/>

    APIs

    Upload

    参数说明类型默认值
    action上传的地址String-
    shape上传按钮形状

    可选值:
    'card'    		Enum-
    accept接受上传的文件类型 (image/png, image/jpg, .doc, .ppt) 详见 input accept attributeString-
    data上传额外传参Object/Function-
    headers设置上传的请求头部Object-
    withCredentials是否允许请求携带 cookieBooleantrue
    beforeUpload可选参数, 详见 beforeUpload

    签名:
    Function(file: Object, options: Object) => Boolean/Object/Promise
    参数:
    file: {Object} 所有文件
    options: {Object} 参数
    返回值:
    {Boolean/Object/Promise} 返回值作用见demo
    		Functionfunc.noop
    onProgress上传中

    签名:
    Function() => void    		Functionfunc.noop
    onSuccess可选参数，上传成功回调函数，参数为请求下响应信息以及文件

    签名:
    Function(file: Object, value: Array) => void
    参数:
    file: {Object} 文件
    value: {Array} 值    		Functionfunc.noop
    onError可选参数，上传失败回调函数，参数为上传失败的信息、响应信息以及文件

    签名:
    Function(file: Object, value: Array) => void
    参数:
    file: {Object} 出错的文件
    value: {Array} 当前值    		Functionfunc.noop
    children子元素ReactNode-
    timeout设置上传超时,单位msNumber-
    method上传方法

    可选值:
    'post', 'put'    		Enum'post'
    request自定义上传方法

    签名:
    Function(option: Object) => Object
    参数:
    option: {Object} null
    返回值:
    {Object} object with abort method
    		Function-
    name文件名字段String-
    onSelect选择文件回调

    签名:
    Function() => void    		Functionfunc.noop
    onDrop放文件

    签名:
    Function() => void    		Functionfunc.noop
    value文件列表Array-
    defaultValue默认文件列表Array-
    listType上传列表的样式

    可选值:
    'text'(文字)
    'image'(图文)
    'card'(卡片)    		Enum-
    formatter数据格式化函数，配合自定义 action 使用，参数为服务器的响应数据，详见 formatter

    签名:
    Function(response: Object, file: File) => void
    参数:
    response: {Object} 返回
    file: {File} 文件对象    		Function-
    limit最大文件上传个数NumberInfinity
    dragable可选参数，是否支持拖拽上传，ie10+ 支持。Boolean-
    useDataURL可选参数，是否本地预览Boolean-
    disabled可选参数，是否禁用上传功能Boolean-
    onChange上传文件改变时的状态

    签名:
    Function(info: Object) => void
    参数:
    info: {Object} 文件事件对象    		Functionfunc.noop
    afterSelect可选参数, 用于校验文件,afterSelect仅在 autoUpload=false 的时候生效,autoUpload=true时,可以使用beforeUpload完全可以替代该功能.

    签名:
    Function(file: Object) => Boolean
    参数:
    file: {Object} null
    返回值:
    {Boolean} 返回false会阻止上传,其他则表示正常
    		Functionfunc.noop
    onRemove移除文件回调函数

    签名:
    Function(file: Object) => Boolean/Promise
    参数:
    file: {Object} 文件
    返回值:
    {Boolean/Promise} 返回 false、Promise.resolve(false)、 Promise.reject() 将阻止文件删除
    		Functionfunc.noop
    autoUpload自动上传Booleantrue
    progressProps透传给Progress propsObject-
    isPreview是否为预览态Boolean-
    renderPreview预览态模式下渲染的内容

    签名:
    Function(value: number) => void
    参数:
    value: {number} 评分值    		Function-
    fileKeyName文件对象的 key nameString-
    fileNameRenderlist 的自定义文件名渲染

    签名:
    Function(file: Object) => Node
    参数:
    file: {Object} 文件
    返回值:
    {Node} react node
    		Function-
    actionRender操作区域额外渲染

    签名:
    Function(file: Object) => Node
    参数:
    file: {Object} 文件
    返回值:
    {Node} react node
    		Function-

    Upload.Card

    继承 Upload 的 API，除非特别说明

    参数说明类型默认值
    onPreview点击图片回调

    签名:
    Function() => void    		Functionfunc.noop
    onChange改变时候的回调

    签名:
    Function() => void    		Functionfunc.noop
    onRemove点击移除的回调

    签名:
    Function() => void    		Function-
    onCancel取消上传的回调

    签名:
    Function() => void    		Function-
    itemRender自定义成功和失败的列表渲染方式

    签名:
    Function() => void    		Function-

    Upload.Dragger

    IE10+ 支持。继承 Upload 的 API，除非特别说明

    Upload.Selecter

    [底层能力] 可自定义样式的文件选择器

    参数说明类型默认值
    disabled是否禁用上传功能Boolean-
    multiple是否支持多选文件，ie10+ 支持。开启后按住 ctrl 可选择多个文件Booleanfalse
    webkitdirectory是否支持上传文件夹，仅在 chorme 下生效Boolean-
    dragable是否支持拖拽上传，ie10+ 支持。Boolean-
    accept接受上传的文件类型 (image/png, image/jpg, .doc, .ppt) 详见 input accept attributeString-
    onSelect文件选择回调

    签名:
    Function() => void    		Functionfunc.noop
    onDragOver拖拽经过回调

    签名:
    Function() => void    		Functionfunc.noop
    onDragLeave拖拽离开回调

    签名:
    Function() => void    		Functionfunc.noop
    onDrop拖拽完成回调

    签名:
    Function() => void    		Functionfunc.noop

    Method

    Upload.Uploader

    [底层能力] 文件上传核心功能 let uploader = new Upload.Uploader([options]);

    options

    参数说明类型默认值
    action上传的地址String-
    data上传额外传参Object/Function-
    headers设置上传的请求头部Object-
    withCredentials是否允许请求携带 cookieBooleanfalse
    onProgress上传中

    签名:
    Function() => void    		Functionnoop
    onSuccess上传成功回调函数，参数为请求下响应信息以及文件

    签名:
    Function() => void    		Functionnoop
    onError可选参数，上传失败回调函数，参数为上传失败的信息、响应信息以及文件

    签名:
    Function() => void    		Functionnoop

    自定义Request

    某些场景下需要自定义Request,例如对接AWS S3 jd-sdk or aliyun oss sdk,. Upload 支持 传入自定义的 request方法.

            function customRequest(option) {
            /* coding here */
            return {abort() {/* coding here */}};
        }

        <Upload request={customRequest}/>

    customRequest被传入一个 object,包含以下属性:

    • onProgress: (event: { percent: number }): void
    • onError: (event: Error, body?: Object): void
    • onSuccess: (body: Object): void
    • data: Object // 额外的数据
    • filename: String // 文件名
    • file: File // 原生File对象
    • withCredentials: Boolean // 是否携带cookie
    • action: String // 请求地址
    • method: String // 请求类型 post/put
    • timeout: Number // 超时
    • headers: Object // 请求头

    request需要返回一个包含abort方法的对象,用于中断上传

    • abort(file?: File) => void: abort the uploading file

    具体实现参照 Upload 默认request方法: https://github.com/alibaba-fusion/next/blob/master/src/upload/runtime/request.jsx

    ErrorCode

    ErrorCode含义
    EXCEED_LIMIT当设置了limit, 选中的文件 + 已上传的文件 > limit 报错
    BEFOREUPLOAD_REJECTBeforeUpload中返回了 false/Promise.resolve(false)/Promise.reject()
    RESPONSE_FAIL返回提响应错误

    所有的值在Upload.ErrorCode.

    onChange 返回结构

        {
      uid: 'uid',       // 文件唯一标识
      name: 'xx.png'    // 文件名
      state: 'done',    // 状态有：selected uploading done error
      response: {"success":true}  // 服务端响应内容
      url: 'https://img.alicdn.com/tps/TB19O79MVXXXXcZXVXXXXXXXXXX-1024-1024.jpg',
      imgURL: 'https://img.alicdn.com/tps/TB19O79MVXXXXcZXVXXXXXXXXXX-1024-1024.jpg', // 头像(可选)
      downloadURL: 'https://img.alicdn.com/tps/TB19O79MVXXXXcZXVXXXXXXXXXX-1024-1024.jpg'   // 下载(可选)
    }

    接口 response 返回数据格式要求

        {
      "success": true,
      "message": "上传成功",                                  // success=false 时候可以展示错误
      "url": "https://img.alicdn.com/tps/TB19O79MVXXXXcZXVXXXXXXXXXX-1024-1024.jpg"             // 返回结果
      "imgURL": "https://img.alicdn.com/tps/TB19O79MVXXXXcZXVXXXXXXXXXX-1024-1024.jpg",         // 图片预览地址 (非必须)
      "downloadURL": "https://img.alicdn.com/tps/TB19O79MVXXXXcZXVXXXXXXXXXX-1024-1024.jpg",    // 文件下载地址 (非必须)
    }

    后端数据格式化

    通过 formatter 将来自后端的不规则数据转换为符合组件要求的数据格式

    • 假设 服务器的响应数据如下
        {
      "status": "success",                              // 上传成功返回码
      "img_src": "https://img.alicdn.com/tps/TB19O79MVXXXXcZXVXXXXXXXXXX-1024-1024.jpg",   // 图片链接
    }
    • 转换方法
        <Upload
      action="http://127.0.0.1:3001/upload"
      formatter={(res, file) => {
        // 函数里面根据当前服务器返回的响应数据
        // 重新拼装符合组件要求的数据格式
        return {
          success: res.status === 'success',
          url: res.img_src,
        }
      }}
    />

    Upload 服务端代码样例

    Next Upload组件上传文件使用的multipart/form-data方式上传文件,具体实现是在支持FormData对象的浏览器中使用xhr对象发送formdata。在不支持FormData对象的浏览器如IE9, 使用iframe原生表单实现。

    各个语言的服务端框架,必然是可以处理multipart/form-data类型的请求,并解析出文件。一下给出两种语言的样例代码

    Demo

    文字列表

    Loading demo...

    提醒: //upload-server.alibaba.net/upload.do接口: 该接口仅作为测试使用,业务请勿使用 该接口仅支持图片上传,其他文件类型接口请自备

    图片列表

    Loading demo...

    提醒: //upload-server.alibaba.net/upload.do接口: 该接口仅作为测试使用,业务请勿使用 该接口仅支持图片上传,其他文件类型接口请自备

    卡片

    Loading demo...

    提醒: //upload-server.alibaba.net/upload.do接口: 该接口仅作为测试使用,业务请勿使用 该接口仅支持图片上传,其他文件类型接口请自备

    拖拽上传

    Loading demo...

    提醒: //upload-server.alibaba.net/upload.do接口: 该接口仅作为测试使用,业务请勿使用 该接口仅支持图片上传,其他文件类型接口请自备

    自定义上传参数

    Loading demo...

    通过 data 控制自定义参数

    提醒: //upload-server.alibaba.net/upload.do接口: 该接口仅作为测试使用,业务请勿使用 该接口仅支持图片上传,其他文件类型接口请自备

    提交上传

    Loading demo...

    通过按钮点击提交上传

    提醒: //upload-server.alibaba.net/upload.do接口: 该接口仅作为测试使用,业务请勿使用 该接口仅支持图片上传,其他文件类型接口请自备

    粘贴上传

    Loading demo...

    提醒: //upload-server.alibaba.net/upload.do接口: 该接口仅作为测试使用,业务请勿使用 该接口仅支持图片上传,其他文件类型接口请自备

    个数限制

    Loading demo...

    提醒: //upload-server.alibaba.net/upload.do接口: 该接口仅作为测试使用,业务请勿使用 该接口仅支持图片上传,其他文件类型接口请自备

    大小限制

    Loading demo...

    提醒: //upload-server.alibaba.net/upload.do接口: 该接口仅作为测试使用,业务请勿使用 该接口仅支持图片上传,其他文件类型接口请自备

    内容回填

    Loading demo...

    提醒: //upload-server.alibaba.net/upload.do接口: 该接口仅作为测试使用,业务请勿使用 该接口仅支持图片上传,其他文件类型接口请自备

    上传前预处理

    Loading demo...

    使用beforeUpload去控制上传行为

    提醒: //upload-server.alibaba.net/upload.do接口: 该接口仅作为测试使用,业务请勿使用 该接口仅支持图片上传,其他文件类型接口请自备

    额外内容

    Loading demo...

    提醒: //upload-server.alibaba.net/upload.do接口: 该接口仅作为测试使用,业务请勿使用 该接口仅支持图片上传,其他文件类型接口请自备

    裁剪上传

    Loading demo...

    提醒: //upload-server.alibaba.net/upload.do接口: 该接口仅作为测试使用,业务请勿使用 该接口仅支持图片上传,其他文件类型接口请自备

    1. Upload 上传组件
    2. 基本用法
    3. 文件上传
    4. 接口返回数据格式要求
    5. 后端数据格式化
    6. APIs
    7. Upload
    8. Upload.Card
    9. Upload.Dragger
    10. Upload.Selecter
    11. Method
    12. Upload.Uploader
    13. options
    14. 自定义Request
    15. ErrorCode
    16. onChange 返回结构
    17. 接口 response 返回数据格式要求
    18. 后端数据格式化
    19. Upload 服务端代码样例
    20. Demo
    21. 文字列表
    22. 图片列表
    23. 卡片
    24. 拖拽上传
    25. 自定义上传参数
    26. 提交上传
    27. 粘贴上传
    28. 个数限制
    29. 大小限制
    30. 内容回填
    31. 上传前预处理
    32. 额外内容
    33. 裁剪上传