外掛使用手冊:vue-simple-upload 上傳外掛[支援檔案、資料夾上傳]
前言
近期有一個專案需求是做一個 公司內部的 知識庫 模組。要求實現檔案、資料夾上傳,以及後續的文件線上預覽、下載、刪除、新建空資料夾等類似於一個網盤的業務。搜尋一圈,發現了這個外掛,而且外掛的引數事件資訊也挺齊全,缺點就是貌似作者沒有維護了,後續出現了bug只能自行解決。用於一個基本的檔案、資料夾上傳需求還是可以滿足,使用的話還請自行思量。
簡介
vue-simple-uploader 是基於 simple-uploader.js 和Vue結合做的一個上傳元件,自帶 UI,可覆蓋、自定義。它支援檔案、多檔案、資料夾上傳;支援拖拽檔案、資料夾上傳;可暫停、繼續上傳;支援秒傳;上傳佇列管理,支援最大併發上傳;分片上傳;支援進度、預估剩餘時間、出錯自動重試、重傳等操作。
檢視演示:https://www.helloweba.net/demo/2020/vueuploader/#/
配置
安裝:
npm install vue-simple-uploader --save
初始化,在main.js中新增如下程式碼:
import Vue from 'vue'
import uploader from 'vue-simple-uploader'
import App from './App.vue'
Vue.use(uploader)
使用<template> <uploader :options="options" class="uploader-example" >
<uploader-unsupport></uploader-unsupport> <uploader-drop> <p>Drop files here to upload or</p> <uploader-btn>select files</uploader-btn> <uploader-btn :attrs="attrs">select images</uploader-btn> <uploader-btn:directory="true">select folder</uploader-btn> </uploader-drop> <uploader-list></uploader-list> </uploader> </template> <script> export default { data () { return { options: { target: 'http://localhost:9245/upload', testChunks: false, chunkSize: 1024*1024*2, //1MB simultaneousUploads: 3, //併發上傳數 headers: { 'access-token': 'abcd1234' },
}, attrs: { accept: 'image/*' } } } } </script> <style> .uploader-example { width: 880px; padding: 15px; margin: 40px auto 0; font-size: 12px; box-shadow: 0 0 10px rgba(0, 0, 0, .4); } .uploader-example .uploader-btn { margin-right: 4px; } .uploader-example .uploader-list { max-height: 440px; overflow: auto; overflow-x: hidden; overflow-y: auto; } </style>
傳遞引數
外掛使用時,上傳請求都會包含如下分塊資訊:
-
chunkNumber
: 當前塊的次序,第一個塊是 1,注意不是從 0 開始的。 -
totalChunks
: 檔案被分成塊的總數。 -
chunkSize
: 分塊大小,根據totalSize
和這個值你就可以計算出總共的塊數。注意最後一塊的大小可能會比這個要大。 -
currentChunkSize
: 當前塊的大小,實際大小。 -
totalSize
: 檔案總大小。 -
identifier
: 這個就是每個檔案的唯一標示。 -
filename
: 檔名。 -
relativePath
: 資料夾上傳的時候檔案的相對路徑屬性。
後端可根據傳遞的資訊自由處理;一般是一個檔案表一個資料夾表做關聯。
狀態碼
-
200
,201
,202
: 當前塊上傳成功,不需要重傳。 -
404
,415
.500
,501
: 當前塊上傳失敗,會取消整個檔案上傳。 - 其他狀態碼: 出錯了,但是會自動重試上傳。
配置項
由於是對原simple-upload.js做的封裝,大多數的配置可以參考原生js文件,部分配置與原生有些許不同,請注意仔細檢視相關參考文件。
target
:目標上傳地址URL,預設值為 '/'。
chunkSize
:分片時按照該值來分。最後一個上傳分片的大小是可能是大於等於1倍的這個值但是小於兩倍的這個值大小
simultaneousUploads
:併發上傳數,預設 3。
fileParameterName
:上傳檔案時檔案的引數名,預設 file。
headers
:額外的一些請求頭,例如有時我們需要在header中向後臺傳遞token,預設為物件: {}。
maxChunkRetries
:最大自動失敗重試上傳次數,值可以是任意正整數,如果是 undefined 則代表無限次,預設 0。
chunkRetryInterval
:重試間隔,值可以是任意正整數,如果是 null 則代表立即重試,預設 null。
parseTimeRemaining(timeRemaining, parsedTimeRemaining) {Function}
:格式化剩餘時間。以下程式碼把英文時間轉成中文:
parseTimeRemaining: function (timeRemaining, parsedTimeRemaining) {
return parsedTimeRemaining
.replace(/\syears?/, '年')
.replace(/\days?/, '天')
.replace(/\shours?/, '小時')
.replace(/\sminutes?/, '分鐘')
.replace(/\sseconds?/, '秒')
}
屬性
autoStart {Boolean}
:預設 true, 是否選擇檔案後自動開始上傳。
fileStatusText {Object}
:檔案狀態,檔案在上傳時會響應幾種狀態:
{
success: 'success',
error: 'error',
uploading: 'uploading',
paused: 'paused',
waiting: 'waiting',
}
事件
fileAdded(file)
:添加了一個檔案事件,一般用做檔案校驗,比如要校驗檔案md5時,先觸發該事件。
fileSuccess(rootFile, file, message, chunk)
:一個檔案上傳成功事件,第一個引數 rootFile 就是成功上傳的檔案所屬的根 Uploader.File 物件,它應該包含或者等於成功上傳檔案;第二個引數 file 就是當前成功的 Uploader.File 物件本身;第三個引數就是 message 就是服務端響應內容,永遠都是字串;第四個引數 chunk 就是 Uploader.Chunk 例項,它就是該檔案的最後一個塊例項,如果你想得到請求響應碼的話,chunk.xhr.status 就是。
fileError(rootFile, file, message, chunk)
:上傳過程中出錯了。
fileProgress(rootFile, file, chunk)
:一個檔案在上傳中。
注意:所有的事件都會通過 lodash.kebabCase 做轉換,例如 fileSuccess
就會變成 file-success
。
Uploader.File
mounted () {
this.$nextTick(() => {
window.uploader = this.$refs.uploader.uploader
})
}
//例項呼叫:
uploader.cancel()
.getRoot()
得到當前檔案所屬的根檔案,這個根檔案就是包含在 uploader.fileList
中的.
.progress()
返回一個 0 到 1 的數字,代表當前上傳進度。
.pause()
暫停上竄檔案。
.resume()
繼續上傳檔案。
.cancel()
取消上傳且從檔案列表中移除。
.retry()
重新上傳檔案。
.bootstrap(
)
重新初始化 Uploader.File
物件的狀態,包括重新分塊,重新建立新的 XMLHttpRequest 例項。
.isUploading()
檔案是否扔在上傳中。
.isComplete()
檔案是否已經上傳完成。
.sizeUploaded()
已經上傳大小。
.timeRemaining()
剩餘時間,基於平均速度的,如果說平均速度為 0,那麼值就是 Number.POSITIVE_INFINITY
。
.getExtension()
得到小寫的字尾。
.getType()
得到檔案型別。
開發遇到的問題
1、上傳資料夾的大致原理本質上還是上傳的檔案,只是檔案被帶上了資料夾相關的路徑,空資料夾是無法發起請求的,如需完成新建空資料夾的操作需要單獨呼叫新建資料夾介面完成一個對資料夾表的新增操作。
2、當上傳資料夾時,若資料夾包含子資料夾的情況,由於上傳是非同步的,有可能導致子檔案的請求先被請求成功導致上傳的資料夾結構異常,需要後端做同步處理。
3、併發上傳數 注意根據業務調整,一般的資料夾上傳檔案一般都比較多。
1、原文:使用vue-simple-uploader上傳檔案和資料夾 作者:月光光
2、simple-uploader.js github地址及參考文件 完成配置項請點此檢視