yj-filepool / 文件上传池

功能点

• ✔ v-model双绑
• ✔ 支持分片上传/断点续传
• ✔ 支持上传进度显示
• ✔ 支持格式限制/大小限制/数量限制 可针对不同类型分别设置
• ✔ 支持上传后预览/禁用时预览
• ✔ 全局安装/局部引入 通用参数仅需配置一次
• ✔ 支持自定义上传/自定义上传参数/自定义上传方法
• ✔ 自定插槽，展示和上传按钮支持通过插槽配置
• ✔ 支持单条取消上传，重新上传功能

安装

$ yarn add yj-filepool

// sliceFile, MB, GB 仅作为工具函数、常量 可选
import Filepool from 'yj-filepool'

// 组件内引入
components: { Filepool }

// 全局引入
Vue.use(Filepool, {})

使用

<Filepool v-model="" fileType="video"/>

属性

| 属性名 | 说明 | 配置方式 | 数据类型 | 可选值 | 默认值 | | --- | --- | --- | --- | --- | --- | | v-model | 文件链接 | props | string / array | | | | multiple | 是否上传多个文件 | props | boolean | | false | | upload | 局部自定义上传方法 | props | Function | | undefined | | originalName | 是否显示原始文件名称 | props | boolean | | false | | disabled | 是否禁用 | props | boolean | | false | | fileTypeCatalog | 文件目录，仅支持全局配置 | global | object | | see below | | fileType | 指定使用fileTypeCatalog中的哪一个 | props | string, array | prop of fileTypeCatalog | | | maxSize | 大小限制 单位MB | props | number | | 200 | | count | 数量限制， multiple模式时有效 | props | number | | 1 | | delConfirmation | 是否在删除文件时弹框确认 | global, props | boolean | | false | | placeholder | 提示信息（hint） | global, props | string | | '点击上传' | | localMode | 本地模式，开启本地模式文件将不会自动上传，直接返回整个文件原始信息 | props | boolean | | false | | preview | 自定义预览，参数为点击的文件信息 | props | function | | undefined | | formParam | 表单额外参数，会通过参数传给上传方法 | props | object | | {} |

插槽（slot）

| 名称 | 参数 | 说明 | | --- | --- | --- | | default | | 默认插槽，覆盖默认上传文件区域 | | fileList | fileList | 文件列表插槽，传入此插槽可完全自定义文件列表展示区域 |

函数

| 名称 | 参数 | 说明 | | --- | --- | --- | | filesChange | fileList | 文件传后的回调，字段见下表 |

interface File {
  // 文件名称
  fileName?: string;
  // 文件对象
  file?: any;
  // 上传进度
  progress?: number;
  // 0 上传中  1 失败  2上传成功 3已关闭
  status?: number;
  // 文件访问路径
  url?: string;
  // 文件类型
  type?: string;
  // 文件类型
  size?: string | number;
  // 文件类型
  loading?: boolean;
}

接口相关

由于分片上传的实现由后端主导 五花八门 无法统一 故上传的整个过程放开自定义

| Attribute | Description | Configuration Mode | Type | Accepted Values | Default | | --- | --- | --- | --- | --- | --- | | upload | 自定义上传的整个过程 | global, props | function | see below | |

upload

import Filepool from 'filepool'
import request from '@/utils/request' // 你的axios封装

Vue.use(Filepool, {
  upload ({ file, jsonToFormData, }) {
    return new Promise((resolve, reject) => {
      request({
        url: '',
        method: 'POST',
        data: jsonToFormData({
          file,
        }),
      }).then(res => {
        if (typeof res?.data === 'string') {
          resolve(res.data)
        } else {
          reject(res.message)
        }
      }).catch(e => {
        reject(e)
      })
    })
  },
})

取消上传

支持对单个或多个文件单独控制是否需取消上传，通过监听 upload 方法中是否配置 signal 参数自动判断是否需要取消上传，支持对上传列表中的单个文件取消。配置方式见如下上传示例

相对完整的分片上传示例

含中途取消、进度显示、断点续传等

import Filepool from 'filepool'
import request from '@/utils/request' // 你的axios封装
import { CancelToken } from 'axios'

Vue.use(Filepool, {
  /**
   * @return {promise}
   */
  upload ({
    file, // 用户选择的二进制文件
    
    fileType, // 当前实例的文件类型
    
    /**
     * json转FormData
     *
     * @param {json} param - 参数
     * @return {formData} formData格式的参数
     */
    jsonToFormData,
    
    /**
     * 设置上传进度
     *
     * @param {number} progress - 进度 范围[0, 1]
     */
    setProgress,
    
    /**
     * 切割文件（分片上传时有用）
     *
     * @param {file} file - 二进制文件
     * @param {number} chunkSize - 分片大小 单位字节 默认10M
     * @return {array} 文件分片
     */
    sliceFile,
    
    MB, GB, // 文件容量单位 方便用于chunkSize参数

    controller, // 用于通知取消上传事件

    formParam
  }) {
    const chunkSize = 10 * MB

    setProgress(0)
    

    const retryTimes = 3  // 失败重试次数
    let failTimes = 0
    let cancelUpload = null

    let chunks = sliceFile(file, chunkSize), count = 0
    
    const formData = jsonToFormData({
      domainId: 4,
      dir: fileType,
      chunkTotal: chunks.length.toString(),
      fileName: file.name,
      ...(formParam || {})
    })

    return new Promise((resolve, reject) => {
      function recursion () {
        formData.set('file', chunks[count])
        formData.set('chunk', count.toString())
        request({
          baseURL: '',
          url: '',
          method: 'POST',
          data: formData,
          timeout: 0,
          onUploadProgress (progressEvent) {
            if (progressEvent.lengthComputable) {
              const pct = (chunkSize * count + progressEvent.loaded) / file.size
              setProgress(pct >= 1 ? .99 : pct)
            }
          },
          cancelToken: new CancelToken(function executor (c) {
            // executor 函数接收一个 cancel 函数作为参数
            cancelUpload = c
          }),

          signal: controller.signal // 用于通知取消上传事件，不配置的话不支持取消上传
        }).then(res => {
          let data = 'data' in res ? res.data : res
          if (data?.status === '200') {
            setProgress(1)
            resolve(data.url)
          } else if (count++ < chunks.length - 1) {
            formData.set('taskId', data.url)
            recursion()
          } else {
            setProgress(1)
            reject('上传失败')
          }
        }).catch(e => {
          // 断点续传
          if (failTimes++ < retryTimes) {
            recursion()
          } else {
            reject('上传失败')
          }
        })
      }

      recursion()
    })
  }
})

文件形态

• 服务器模式：配置了upload时进入该模式

文件目录

你可以全局定义一个文件目录 预设一些你可能用到的文件类型（任何类型都可以） 并规定这些类型的格式和大小 在组件中使用fileType属性来对应

默认值

fileTypeCatalog: {
  image: {
    maxSize: 10,
    accept: '.jpg,.jpeg,.png',
  },
  video: {
    maxSize: 200,
    accept: '.mp4',
  },
  audio: {
    maxSize: 60,
    accept: '.mp3',
  },
  apk: {
    maxSize: 200,
    accept: '.apk',
  },
  excel: {
    maxSize: 100,
    accept: '.xlsx,.xls',
  },
}

例子

<template>
  <Filepool fileType="abc"/>
</template>

<script>
import Filepool from 'filepool'

Vue.use(Filepool, {
  fileTypeCatalog: {
    abc: {
      maxSize: 10,
      accept: '.abc',
    },
  }
})
</script>

获取文件上传原始信息

监听事件 filesChange 即可

Notice

• 全局配置被props中的同名参数覆盖 对象会进行混入

• maxSize权重排序：props ＞ fileTypeCatalog中对应的maxSize ＞ 全局默认的maxSize

• 如果仅上传图片 请使用yj-imgpond（附带图片编辑功能）

升级日志

v3.0.16

兼容后端上传文件路径后在路径后添加的url参数

v3.0.15

新增formParam参数，支持在上传文件时增加额外的参数

v3.0.13

新增支持文件取消及继续上传功能，文件上传中时可以点击取消上传，点击文件将不会上传，支持点击重新上传或删除该文件

v3.0.12

新增支持自定义预览功能，可以自己自定义如何预览文件，参数名为 preview 的函数，详见文档

v3.0.11

支持本地模式，可以仅选中文件，不自动上传，方便自行处理上传逻辑