博客

应用开发平台前端集成vue-simple-uploader实现文件分块上传

  • Post author:
  • Post category:vue




背景

文件的上传是系统的必备功能，Element提供了上传组件upload，也基本能满足常见常用的文件上传功能，特别是应对小型文件（10M以下）的处理。但如果是遇到要求更多更高的场景，上传几百兆甚至上G的视频文件，要求分块上传，能断点续传，显示进度，能暂停，能重试……这时候就显得乏力了。如果基于upload实现，需要附加大量的二次开发，这未必是一种最佳实现方案。

这时候，就需要找一找看一看，市面上是否有现成的“轮子”可用了。

接下来，分两篇，分别介绍下前端实现和后端实现，今天首先来说下前端那些事儿。



技术选型

vue-simple-uploader，作者对vue3做了适配。

官网

https://github.com/simple-uploader/vue-uploader/blob/vue3/README_zh-CN.md



特性

  • 支持文件、多文件、文件夹上传
  • 支持拖拽文件、文件夹上传
  • 统一对待文件和文件夹，方便操作管理
  • 可暂停、继续上传
  • 错误处理
  • 支持“快传”，通过文件判断服务端是否已存在从而实现“快传”
  • 上传队列管理，支持最大并发上传
  • 分块上传
  • 支持进度、预估剩余时间、出错自动重试、重传等操作



功能设计

组件提供了通用能力，整合到平台中，需要根据需求做定制和集成。

在本平台中，我使用该上传组件，主要解决的是与业务实体关联的附件，不同场景下文件有大有小。

需要支持文件、多文件上传，但不需要直接上传文件夹（上传文件夹通常做文档库、网盘场景中需要）。

暂停、重试、分块、预估时间、进度显示、重传这些是需要的，但快传、秒传功能不需要（快传、秒传往往只在互联网应用的网盘应用场景有需求，企业应用里都是些独立的，不重复的文件）。



安装及注册

安装，执行如下命令 

pnpm install vue-simple-uploader@next --save

初始化，修改main.js，全局注册 

import uploader from 'vue-simple-uploader'
import 'vue-simple-uploader/dist/style.css'

// 创建实例
const setupAll = async () => {
  const app = createApp(App)

  await setupI18n(app)

  setupStore(app)

  setupGlobCom(app)

  setupRouter(app)

  setupPermission(app)

  ……略

  // 文件上传
  app.use(uploader)

  app.mount('#app')
}



封装组件



上传组件

<template>
  <uploader
    ref="uploader"
    :options="finalOptions"
    :file-status-text="statusText"
    :show-success-files="showSuccessFiles"
    :single-flag="singleFlag"
    :auto-start="autoStart"
    :show-list-flag="showListFlag"
    @file-complete="fileComplete"
    @file-added="fileAdded"
  />
</template>

<script>
import { getToken } from '@/utils/auth'
export default {
  components: {},
  props: {
    options: {
      type: Object,
      required: false,
      default() {
        return {}
      }
    },
    singleFlag: {
      type: Boolean,
      default: false
    },
    autoStart: {
      type: Boolean,
      default: true
    },
    // 是否显示文件列表
    showListFlag: {
      type: Boolean,
      default: true
    },
    entityType: {
      type: String,
      required: true
    },
    entityId: {
      type: String,
      default: '',
      required: true
    },
    moduleCode: {
      type: String,
      required: true
    },
    showSuccessFiles: {
      type: Boolean,
      default: false,
      required: false
    },
    serverUrl: {
      type: String,
      default: '',
      required: true
    }
  },
  data() {
    const token = getToken()
    return {
      defaultOptions: {
        target: import.meta.env.VITE_BASE_URL + this.serverUrl,
        testChunks: false,
        maxChunkRetries: 3,
        chunkSize: 10485760,
        query: {
          entityType: this.entityType,
          entityId: this.entityId,
          moduleCode: this.moduleCode
        },
        headers: { 'X-Token': token },
        generateUniqueIdentifier: () => {
          // 业务主键+时间戳最大限度降低并发冲突发生的概率
          return this.entityId + new Date().getTime()
        },
        parseTimeRemaining(timeRemaining, parsedTimeRemaining) {
          return parsedTimeRemaining
            .replace(/\syears?/, '年')
            .replace(/\days?/, '天')
            .replace(/\shours?/, '时')
            .replace(/\sminutes?/, '分')
            .replace(/\sseconds?/, '秒')
        }
      },
      statusText: {
        success: '100%',
        error: '失败',
        uploading: '上传中',
        paused: '暂停中',
        waiting: '等待中'
      }
    }
  },
  computed: {
    finalOptions: function () {
      const opts = Object.assign(this.defaultOptions, this.options)
      return opts
    }
  },
  watch: {
    entityId: function () {
      this.$refs.uploader.options.query.entityId = this.entityId
    }
  },
  methods: {
    fileComplete(file) {
      this.$emit('fileComplete', file)
    },
    fileAdded(file) {
      this.$emit('fileAdded', file)
    }
  }
}
</script>

有几个需要注意的点，下面来说说。

首先，为了简化使用方设置，我先通过defaultOptions，将组件大部分公用配置设置好，作为缺省配置。同时将可能需要设置的属性作为props提供出来，供使用方按需调整。

其次，受组件自身限制，没法走前端的api调用框架axios，而是在组件配置options的target属性指定了文件上传的后端地址。

再次，平台使用JWT做身份认证，绕过api调用框架axios的结果就是没有自动附加token，同样需要在组件配置中附加，否则后端会视为未授权。 

 const token = getToken()
    return {
      defaultOptions: {
       ……
      headers: { 'X-Token': token }
       ……

最后，我加入了平台自己的控制，即将模块编码moduleCode，实体类型entityType和实体标识entityId也传入了进来，并通过组件的query属性传给了后端，这几个参数，用于后端来生成结构化的保存路径。

image.png

这么做的主要目的，除了分门别类存储附件外，还有个显著优势可以按需进行附件归档。比如系统运行3年了，磁盘占用越来越大，业务上通常只需要查看最近一年的单据和附件，那么就可以把1年前的附件，从服务器上移动到备份服务器上。

默认UI丑到爆，需要自己调整

image.png

调整后效果如下：

image.png



管理组件

管理组件通常是配合上传组件一起使用的，对上传结果进行预览、验证和移除，如下图所示。

image.png

vue-simple-uploader组件虽然有文件列表，但这个列表实际是有功能缺失的，无法下载，更无法移除，因此自己另行封装了一个。 

<template>
  <el-table :data="entityData" highlight-current-row border>
    <el-table-column type="index" label="序号" sortable width="65" />
    <el-table-column prop="name" label="名称" show-overflow-tooltip />
    <el-table-column prop="size" label="大小" width="80" />

    <el-table-column prop="createTime" label="时间" width="100" />
    <el-table-column fixed="right" label="操作" width="200">
      <template #default="scope">
        <el-button
          type="primary"
          icon="Download"
          class="header-search_button"
          size="small"
          @click="download(scope.row)"
          >下载</el-button
        >
        <el-button
          type="primary"
          icon="Delete"
          class="header-search_button"
          size="small"
          @click="remove(scope.row)"
          >删除</el-button
        >
      </template>
    </el-table-column>
  </el-table>
</template>

<script>
export default {
  components: {},
  props: {
    entityId: {
      type: String,
      default: '',
      required: true
    },
    showDelete: {
      type: Boolean,
      default: true,
      required: false
    }
  },
  data() {
    return {
      entityData: []
    }
  },
  watch: {
    entityId: function () {
      this.list()
    }
  },
  mounted: function () {
    this.list()
  },
  methods: {
    list() {
      if (this.entityId) {
        // 只有当entityId不为空时才发起查询
        this.$api.support.attachment.list({ entityId: this.entityId }).then((res) => {
          this.entityData = res.data
        })
      }
    },
    remove(row) {
      this.$confirm('是否删除该附件?', '确认', {
        type: 'warning'
      })
        .then(() => {
          this.$api.support.attachment.remove(row.id).finally(() => {
            this.list()
          })
        })
        .catch(() => {
          this.$message.info('已取消')
        })
    },
    download(row) {
      this.$api.support.attachment.download(row.id, row.name)
    }
  }
}
</script>



浏览组件

浏览组件通常用于查看视图，即查看当前单据上传了哪些附件，并可以下载，但不能删除，如下图所示：

image.png 

<template>
  <el-row>
    <ul style="margin: 0px; padding: 0px">
      <li
        v-for="item in entityData"
        :key="item.id"
        style="
          line-height: 30px;
          width: 100%;
          overflow: hidden;
          word-break: keep-all;
          white-space: nowrap;
          text-overflow: ellipsis;
        "
      >
        <a :title="item.name" @click="download(item)" class="cursor-pointer">
          <span>&nbsp;&nbsp;{{ item.name }}</span>
          <span>({{ item.size }} )</span>
        </a>
      </li>
    </ul>
  </el-row>
</template>
<script>
export default {
  props: {
    entityId: {
      type: String,
      default: '',
      required: true
    }
  },
  data() {
    return {
      entityData: []
    }
  },
  watch: {
    entityId: function () {
      this.list()
    }
  },
  mounted: function () {
    this.list()
  },
  methods: {
    list() {
      if (this.entityId) {
        // 只有当entityId不为空时才发起查询
        this.$api.support.attachment.list({ entityId: this.entityId }).then((res) => {
          this.entityData = res.data
        })
      }
    },
    download(item) {
      this.$api.support.attachment.download(item.id)
    }
  }
}
</script>



遗留问题

同时使用封装的上传组件和管理组件，会出现下面这种情况，也会影响用户体验。

image.png

官方控件自带的上传文件列表，上传成功的文件没有属性或方法从列表中移除。我尝试过使用fileSuccess事件自己实现逻辑，如下图所示： 

 fileSuccess(rootFile, file) {
      //  文件上传成功后从列表中移除
      // TODO:以下代码未调试成功
      // let index = this.$refs.uploader.fileList.findIndex(
      //   (successFile) => successFile.id === file.id
      // )
      // if (index !== -1) {
      //   console.log(this.$refs.uploader.fileList)
      //   this.$refs.uploader.fileList.splice(index, 1)
      //   console.log(this.$refs.uploader.fileList)
      // }
    }
  }

实际调试发现fileList并不能按预期正常变更集合元素，原因不明。后续有时间了再处理，要么将上面代码逻辑调整好，要么直接基于源码去修改。



开发平台资料

平台名称：一二三开发平台

简介： 企业级通用开发平台

设计资料：

csdn专栏


开源地址：

Gitee


开源协议：MIT


欢迎收藏、点赞、评论，你的支持是我前行的动力。


版权声明：本文为seawaving原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。