uploader-x

文件传输SDK文档

引入方式

建议使用ES6引入。

import {Uploader, FileStatus} from 'power-uploader';

• Uploader：文件传输SDK的构造类
• FileStatus：文件实例的状态
  • INITED：初始状态(beforeFileQueued事件之后就会变更)
  • QUEUED：已经进入队列, 等待上传
  • PROGRESS：上传中
  • ERROR：上传出错，可重试
  • CANCELLED：上传取消，会清出队列
  • INTERRUPT：上传中断，可续传
  • INVALID：文件不合格，不能重试上传

初始化

eg.

let uploader = new Uploader({
    pick: '.ff-wrap .up-btn',
    dnd: 'body, .dnd-area',
    paste: ['body', '.paste-area'],
    listenerContainer: document,
    body: document.body,
    chunked: true,
    chunkSize: 20971520,
    multiple: true,
    withCredentials: false
});

初始化参数

参数名	数据类型	默认值	说明
timeout	Number	0	超时时间，为0时不会设置超时事件
accept	Array	[]	[{extensions: 'jpg', mimeTypes: 'image/*'}]
auto	Boolean	true	是否得到文件后就上传，暂不支持设置为false
sameTimeUploadCount	Number	3	同时上传分片的个数
chunked	Boolean	false	是否开启分片上传
chunkSize	Number	20971520	分片大小，默认是20MB
chunkRetry	Number	2	分片失败重试次数(不建议更改太大)
formData	Object	{}	除了二进制文件外，拓展的formData对象
headers	Object	{}	自定义头
fileVal	String	'file'	formData二进制文件的key
method	String	'post'	请求方法
fileNumLimit	Number	undefined	暂不启用
fileSizeLimit	Number	undefined	暂不启用
fileSingleSizeLimit	Number	undefined	暂不启用
dnd	String	void 0	拖拽区域选择器
pick	String	void 0	点击区域的选择器
pickDir	String	void 0	点击区域的选择器(选择文件夹)
paste	String	void 0	粘贴区域选择器
server	String	''	服务器地址
listenerContainer	DOM	document	事件委托的DOM元素
body	DOM	document.body	动态创建的input插入到的DOM元素
multiple	Boolean	false	是否可以选择多文件上传
withCredentials	Boolean	true	是否开启跨域带cookie
setName	Function	(id) => new Date().getTime() + id	无文件名文件函数
log	Function	console.log	记录log的函数
logLevel	Number	1	暂时不开启使用

其中pick、dnd、paste填写选择器的时候支持Selector String，通过,分隔的Selector String，存放Selector String的数组。

file对象封装

file对象封装在事件回调函数中返回的参数对象里为file的key

• eventEmitter：事件发射器
• ext：文件后缀
• id：文件唯一标识符，eg：WU_FILE_0
• isFile：是否是文件(有可能是目录呢)
• lastModifiedDate：最后修改时间
• loaded：上传字节数
• name：文件名
• path：文件路径
• uploadGroupId：文件组ID
• size：文件大小(字节数)
• source：原生文件对象
• statusText：文件状态，即FileStatus的值
• type：文件的MIME Type，egvideo/mp4

事件

所有的事件的回调函数返回的参数均是一个对象，参数中可能有的值说明

名称	数据类型	说明	存在事件
file	Object	即上面的file对象封装	所有事件
currentShard	Number	当前文件分片，从1开始计算，不是从0开始	大部分事件
shardCount	Number	文件总分片	大部分事件
shard	Blob	分片的二进制对象，一般很少用到	大部分事件
total	Number	文件的总字节数	大部分事件
loaded	Number	文件读取的字节数	uploadProgress
isUploadEnd	Boolean	文件是否传输完毕	uploadProgress
responseText	String	分片请求后的服务端返回	uploadAccept
responseText	String	分片请求后的服务端返回	uploadAccept
error	Error	上传错误信息	uploadError

• beforeFilesSourceQueued: 选择上传一组文件之前 包含目录源信息 @return Object { filesSource, actionType, uploadGroupId } demo

   uploader.on('beforeFilesSourceQueued', (obj) => {
       let {filesSource, actionType, uploadGroupId} = obj;
       if (actionType === 'pickDir') {
           // 选择的是文件夹
       }
       // 超过10个文件不允许上传
       if (filesSource.length > 10) {
           return false;
       }
   });

• filesSourceQueued: 选择上传一组文件之后 文件源信息 @return Object { filesSource, actionType, uploadGroupId } demo

   uploader.on('filesSourceQueued', (obj) => {
       let {filesSource, actionType, uploadGroupId} = obj;
       if (actionType === 'pickDir') {
           // 选择的是文件夹
       }
   });

• beforeFileQueued：文件添加到上传队列之前，可以对文件进行一些过滤，return false;会阻止将该文件加入队列。

  @return Object { file }

  demo

  uploader.on('beforeFileQueued', (obj)=> {
      console.log('beforeFileQueued');
      let { file, setContentType } = obj;
      setContentType('image/png'); // 更改文件的Content-Type  
  
      if (/^[^<>\|\*\?\/]*$/.test(file.name)) {
          let b1 = new Buffer(file.name);
          let bytes = Array.prototype.slice.call(b1, 0);
          if (bytes.length > 128) {
              alert('字符长度过长');
              return false;
          }
      } else {
          alert('存在特殊字符');
          return false;
      }
  
      return true;
  });

• fileQueued：没有被beforeFileQueued阻止，文件已经被添加进队列，等待上传。

  @return Object { file }

  demo

  uploader.on('fileQueued', (obj) => {
      console.log('fileQueued');
      let { file } = obj;
  
      this.setState({
          fileList: [...this.state.fileList, file]
      });
  });

• uploadStart：该文件已经开始上传(第一片分片已经上传了)。

  @return Object { file }

  demo

  uploader.on('uploadStart', (obj)=> {
      console.log('uploadStart');
      let { file } = obj;
  
      // 开始请求的文件statusText属性会有变化
      let newFileList = this.state.fileList.map(fileItem =>
          file.id === fileItem.id ? file : fileItem );
      this.setState({ fileList: newFileList });
  });

• uploadBeforeSend：每一个分片上传之前，可以修改new Uploader的时候传入的部分属性，如server、headers。

  @return Object { file, currentShard[Number], shardCount[Number], shard[Blob] }

  demo

  uploader.on('uploadBeforeSend', (obj)=> {
      console.log('uploadBeforeSend');
      let { file, currentShard, shard, shardCount, config } = obj;
  
      config.headers = {
          'name': file.name,
          'path': '/person/img'
      };
      config.server = 'http://xxx.com/file/upload';
  });

• uploadProgress：上传进度回调。

  @return Object { file, loaded[Number], total[Number], shardLoaded[Number], shardTotal[Number] }

  其中loaded和total是整体文件的，shardLoaded和shardTotal是单个分片的，file.loaded已经是loaded的值。

  demo

  uploader.on('uploadProgress', (obj)=> {
      console.log('uploadProgress');
      let { file, loaded, total, shardLoaded, shardTotal } = obj;
  
      console.log(loaded / total * 100 + '%', file.loaded);
      this.setState({
          fileList: this.state.fileList.map(item => item.id === file.id ? file : item)
      });
  });

• fileMd5Finished：上传进度回调。

  @return Object { file, md5 }

  demo

  uploader.on('fileMd5Finished', async (obj) => {
      let {file, md5} = obj;
      let res = await api.md5Check(md5);
      if (res.ok === true) {
          file.url = res.url;
          file.loaded = file.size;
          file.statusText = FileStatus.COMPLETE;
          render(file); // 渲染文件
          return Uploader.CONSTANTS.MD5_HAS;
      }
  });

• uploadAccept：分片上传成功。

  @return Object { file, shard[Blob], shardCount[Number], currentShard[Number], isUploadEnd[Boolean], responseText[String] }

  demo

  uploader.on('uploadAccept', async(obj)=> {
      console.log('uploadAccept');
      let { file, shard, shardCount, currentShard, isUploadEnd, responseText } = obj;
  });

• uploadSuccess：文件上传成功。

  @return Object { file, currentShard[Number], shardCount[Number], shard[Blob], responseText[String], responseTextArr[Array] }

  demo

  uploader.on('uploadSuccess', (obj) => {
      console.log('uploadSuccess');
      let { file, currendShard, shardCount, shard, responseText, responseTextArr } = obj;
      
      if (shardCount === 1) {
           // use responseText
      } else {
          // use responseTextArr
      }
  
      let newFileList = this.state.fileList.map(item => file.id === item.id ? file : item);
      this.setState({fileList: newFileList});
  });

• uploadEndSend：文件上传结束，成功失败都会触发。

  同uploadSuccess

• uploadError：文件上传失败。

  @return Object { file, error[Error] }

文件夹相关的事件：

• beforeChildFileQueued：文件夹中的子文件入队列之前 @return Object { fileSource, parentEntry, uploadGroupId, actionType }

• childFileQueued：文件夹中的子文件入队列之后 @return Object { fileSource, parentEntry, uploadGroupId, actionType }

• beforeChildDirQueued：文件夹中的子文件夹入队列之前 @return Object { currentEntry, parentEntry, uploadGroupId, actionType }

• childDirQueued：文件夹中的子文件夹入队列之后 @return Object { currentEntry, parentEntry, uploadGroupId, actionType }

• selectDir：选择了文件夹，参数返回entry信息，通过return false; 可以禁止 @return Object { entry, uploadGroupId, actionType }