Skip to content

252352801/js-web-uploader

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Oct 29, 2020
2ffc939 · Oct 29, 2020

History

3 Commits
Oct 29, 2020
May 25, 2020
Oct 29, 2020
Oct 29, 2020
May 25, 2020
May 25, 2020
May 25, 2020
Oct 29, 2020
May 15, 2020
Oct 29, 2020
Oct 29, 2020

Repository files navigation

js-web-uploader

基于html5的文件上传工具

安装

npm install js-web-uploader --save

注意

  • 该上传工具仅包含JavaScript部分
  • 支持文件分块上传、断点续传,秒传
  • 内部http请求使用XHR(XMLHttpRequest)对象,文件分块基于Blob.prototype.slice

使用说明

使用时需创建一个Uploader实例,假设实例为uploader:

  • 批量上传:uploader.upload()
  • 单个文件上传 uploader.queue[0].upload()
  • 批量暂停:uploader.abort()
  • 单个文件上传 uploader.queue[0].abort()
  • 文件状态 uploader.queue[0].status (详见附录2)

普通上传

import { Uploader } from 'js-web-uploader';
const uploader = new Uploader({
	inputElem: 'uploadInput', // 选择文件的元素
	uploadUrl: '',// 文件上传路径
})

分块上传

分块上传需计算文件hash值,并将其作为文件的唯一标识,可参考以下思路:
  • 客户端上传文件分块,同时携带所属文件hash值、文件分块数量、分块索引(第几个分块)
  • 服务器接收文件分块并保存分块信息,文件以hash值作为唯一标识
  • 服务器在每个分块上传后检测是否该文件所有分块已经上传,若已上传所有分块,则将分块合并成文件保存,并将获取文件的url返回给客户端
import { Uploader } from 'js-web-uploader';
const uploader = new Uploader({
        inputElem: 'uploadInput', // 选择文件的元素
        uploadUrl: '',// 文件上传路径
        // 填写chunkSize参数触发分块上传
        chunkSize: 1 * 1024 * 1024, // 分块大小,单位byte,可以为数值或function,function参数qf为队列文件(详见附录1)
        // chunkSize: qf=>1 * 1024 * 1024,
        uploadType: 0, // (分块)上传方式 0-并行上传 1-串行上传 默认值:0
        data:{}, // 上传时携带的数据,值可以是对象或funtion(详见附录1)
      })

断点续传

断点续传基于分块上传,即服务器保存文件已上传分块信息,在上传前获取文件上传状态,将未上传的文件分块继续上传 (继续上传时调用upload方法)

import { Uploader } from 'js-web-uploader';
const uploader = new Uploader({
        // ... 省略其他参数
        /** 检测文件上传状态方法 */
        checkMethod: (qf, resolve) => {
		// 请求文件上传状态
		// 调用 resolve 方法告知已上传分块,传参为数组 例:resolve([0,1,2])
        }
      })

秒传

在checkMethod里向服务器获取文件上传状态

  • 若文件已完成上传,则服务器直接返回文件访问url,客户端在checkMethod里resolve所有分块
  • 若未完成上传,则在checkMethod里resolve已上传分块
import { Uploader } from 'js-web-uploader';
const uploader = new Uploader({
        // ... 省略其他参数
		secondUpload:true,
        checkMethod: (qf, resolve) => {
		// ... 请求文件上传状态
		// 已完成上传
		// 调用 resolve 方法告知已上传分块,若分块数量为3,则:resolve([0,1,2])
			resolve([0,1,2])
        }
      })

API

  • upload() 上传文件
  • setOptions(options) 设置参数
  • remove(index) 删除指定下标的文件(queue中的qf)
  • on(event,callback) 注册监听事件,详见附录
  • trigger(event,...args) 触发指定事件,arg为传入的参数
    // 文件选择时
    uploader.on('select', files => {
      // files-选择的文件列表
    })
    // 移除文件前
    uploader.on('beforeRemove', qfs => {
      // qfs- qf列表
      // 若返回值为 false, 0, '', null中的任一值,则将不执行移除操作
      // 若返回值为Promise实例且resolve false, 0, '', null中的任一值,则将不执行移除操作
    })
    // 移除文件后
    uploader.on('remove', qfs => {
      // qfs- qf列表
    })
    // 超出数量时
    uploader.on('countExceed', (totalCount, maxCount) => {
      // totalCount 总数量
      // maxCount 最大数量
    })
    // 单个文件超出大小限制时
    uploader.on('sizeExceed', (eFiles, maxSize) => {
      // eFiles 超出大小的文件
      // maxSize 文件大小最大值限制
    })
    // 生成分片前
    uploader.on('beforeChunk', qf => {
    })
    // 生成分片后
    uploader.on('beforeChunk', qf => {
    })
    // 生成文件hash值前
    uploader.on('beforeHash', qf => {
    })
    // 生成文件hash值后
    uploader.on('beforeHash', qf => {
    })
    // 进度事件
    uploader.on('progress', (ev, percent) => {
      // ev事件对象
      // percent 单个文件上传百分比
    })
    // 上传成功
    uploader.on('success', (qf,res,chunk) => {
      // qf 详见附录1
      // res 服务器返回结果
      // chunk分块上传时的分块
    })
    // 上传失败
    uploader.on('error', res => {
      // res 发生错误时的结果
    })

附录1 options

options

     // 示例
     const uploader = new Uploader({
        inputElem: 'uploadInput', // 选择文件的元素
        triggerEvent: 'chuange', // 触发事件 默认change
        uploadUrl: '', // 文件上传路径
        name: 'file', // 上传的文件字段名
        hashFile: true, // 是否计算文件hash值 (默认md5)
        hashMethod: (file) => {
          // 可选计算文件hash值的方法,file为文件对象
          // 需返回一个Promise实例,并resolve计算后的hash值
        },
        uploadType: this.uploadType, // 分块上传时上传方式 0-并行上传 1-串行上传
        chunkSize: (qf) => 1 * 1024 * 1024, // 分块大小 单位byte 数值或function qf为队列文件
        headers: (info) => {
          // 请求头 键值对象或返回键值对象的function,info为分块信息
          return {
            // ...
          }
        },
        data: (info) => {
          // 上传时携带的数据,需返回一个对象
          return {
            // ...
          }
        },
        /** 检测文件上传状态方法 */
        checkMethod: (qf, resolve) => {
          // 请求文件上传状态
          // 调用 resolve 方法告知已上传分块,传参为数组 例:resolve([1,2,3])
        }
      })

附录2 文件状态

即uploader.queue[0].status

/** 队列文件状态 */
export const QF_STATUS = {
  pending: 'pending', // 等待上传
  ready: 'ready', // 准备就绪
  hashing: 'hashing', // 正在计算hash值
  hashed: 'hashed', // 计算hash值完成
  chunking: 'chunking', // 正在进行文件分块
  chunked: 'chunked', // 文件分块完成
  checking: 'checking', // 检测文件状态
  checked: 'checked', // 检测文件状态完成
  uploading: 'uploading', // 正在上传
  abort: 'abort', // 中断
  success: 'success', // 上传成功
  error: 'error' // 上传失败
}

附录3 qf

qf为保存在Uploader实例的queue属性(数组)中的对象,qf是QueueFile的实例

      qf = {
        file: null, // 原始文件对象
        fileHash: '', // 文件哈希值
        chunkSize: 0, // 分块大小
        chunks: [
          // 文件分块信息
          // {
          //   index: 0, // 第几个分块
          //   blob: null, // 分块bob数据
          //   percent: 0, // 上传进度
          //   uploaded: false // 是否已上传
          // }
        ],
        percent: 0, // 上传百分比
        status: 'pending', // 状态 见附录2
        response: '' // 服务器返回
        // ...
      }

附录4 chunk

文件分块信息,chunk是Chunk的实例

class Chunk {
    queueFile // qf
    index = 0 // 分块索引
    blob // 分块blob数据
    percent = 0 // 上传百分比
    uploaded = false // 是否已经上传
    response = null // 服务器的返回值
	// ...
}

附录5 info

     info = {
        file: null, // 原始文件对象
        fileHash: '', // 文件哈希值
        chunkSize: 0, // 分块大小
        chunks: [
          // 文件分块信息
          // {
          //   index: 0, // 第几个分块
          //   blob: null, // 分块bob数据
          //   percent: 0, // 上传进度
          //   uploaded: false // 是否已上传
          // }
        ],
        percent: 0, // 上传百分比
        status: 'pending', // 状态 见附录2
        response: '', // 服务器返回
        chunk: null, // 分块的blob数据
        chunkIndex: 0 // 分块索引

        // ...
      }

About

js实现的浏览器文件上传工具

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published