Upload 上传组件

开发指南

何时使用

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

参考文章:

1. Upload 组件的设计思想

2. Upload 组件对接阿里云 OSS/七牛/又拍

API

Upload

Upload.Card

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

Upload.Dragger

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

Upload.Selecter

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

Method

Upload.Uploader

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

options

自定义 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

所有的值在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类型的请求,并解析出文件。一下给出两种语言的样例代码

• Java Springboot 样例

• Node Eggjs 样例

IE9 兼容性

• ie9 下用因为使用 iframe 作为无刷新上传方案，必须保证表单页面的域名和上传的服务器端的域名相同。

• ie9 下服务器端返回数据需要设置头部 context-type 为 text/html，不要设置为 application/json

• 如果只是一级域名相同（taobao.com 为一级域名 shop.taobao.com 为二级域名），可以通过降域的方式实现跨域上传。

假设你表单页面的域是：shop.taobao.com，而上传的服务器端路径却是 upload.taobao.com。服务端返回必须带额外 script 标签

  // script内容
  document.domain="taobao.com";

  {"status":1,"type":"ajax","name":"54.png","url":".\/files\/54.png"}

iframe 上传会额外传递参数 _documentDomain 方便你设置域名

ARIA and KeyBoard