DropzoneJS 使用指南(文件拖拽上传)

《DropzoneJS 使用指南(文件拖拽上传)》

官方文档:http://www.dropzonejs.com/
Github: https://github.com/enyo/dropzone

DropzoneJS is an open source library that provides drag’n’drop file uploads with image previews.

It’s lightweight, doesn’t depend on any other library (like jQuery) and is highly customizable.

装置

你能够只须要看看简朴的例子( 源代码 )便能够最先了。然后继承浏览下面的一步步的指导和差别的装置要领。

下载自力的dropzone.js文件。然后如许引入到html中:

<script src="./path/to/dropzone.js"></script>

Dropzone 如今激活和可用,经由历程window.Dropzone便能够够运用了。

Dropzone不处置惩罚你的文件上传在服务器上。你必需本身完成代码吸收和存储文件。有关更多信息,请拜见部份服务器端完成

完成上面的操纵便能够够运用 Dropzone ,然则假如你想让它你上传的款式看起来像官方页面那样,你须要将下载的dropzones内里的cs发到你的文件夹中并引入。

With component

假如你运用component,你只需增加dropzone依靠:

"enyo/dropzone": "*"

然后如许引入:

var Dropzone = require("dropzone");

如今它已激活,并能够在页面中运用。
基本的CSS款式也包含在组件中,假如你想让它你上传的款式看起来像官方页面那样,你须要将下载的dropzones内里的cs发到你的文件夹中并引入。

With RequireJS

Dropzone 一样为RequireJS供应了AMD模块。

你能够在下载的文件夹中找到dropzone-amd-module

运用

运用 dropzone 的典范的体式格局是经由历程竖立一个表单包含与class="dropzone":

<form action="/file-upload" class="dropzone" id="my-awesome-dropzone">
    <input type="file" name="file" />
</form>

就像如许。dropzone 会经由历程classdropzone找到统统的表单元素,并自动将这些元素初始化,然后点击input挑选文件(或拖拽)以后会依据action指定的地点上传文件。(实在就和一般的文件上传没什么区分,只不过多了个拖拽)

假如你想在后端接收文件的时刻用其他的name而不是上面指定的file,您能够设置dropzone的paramName的选项。

假如你是运用component情势,别忘了require("dropzone");,否则是不会见效的。

假如是运用form表单,完成上面的设置以后,就已能够拖拽上传了,所以假如你不想在写一些js去控制上传中的其他东西,比方进度条、预览地区等,能够在form内加一个包含fallback类的标签,dropzone 会本身处置惩罚fallback类的标签地区,固然这是须要浏览器支撑。假如浏览器不支撑,那末那就将其作为一般的文件上传。
这通常是如许的:

<form action="/file-upload" class="dropzone">
  <div class="fallback">
    <input name="file" type="file" multiple />
  </div>
</form>

手动竖立dropzones

除了直接在form表单中增加classdropzone让其自动竖立外,还能够在非表单元素上面经由历程实例化Dropzone类完成。

<div id="myId" style="width: 800px; height: 300px;"></div>
// Dropzone class:
var myDropzone = new Dropzone("div#myId", { url: "/file/post"});

或假如您运用jQuery,您能够运用jQuery插件Dropzone情势:

// jQuery
$("div#myId").dropzone({ url: "/file/post" });

注重:假如你不是运用一个表单元素,别忘了指定一个url选项,因为Dropzone不晓得上传到那边。

服务器端完成

Dropzone 不供应的服务器端文件处置惩罚的代码,然则文件上传的体式格局是和简朴的表单文件上传是雷同的。比方一般的表单上传是如许:

<form action="" method="post" enctype="multipart/form-data">
  <input type="file" name="file" />
</form>

控制基本的服务器上的文件上传,请检察种种言语相应的文档。这里有一些基本的完成文件:

付费的文档:

假如你须要更多的信息,请看看Dropzone FAQ

设置

有两种体式格局设置 dropzone:

要领一:

在html元素上增加dropzone 款式类,然后就不须要手动运用js去实例化了,然则你的一些设置Dropzone.options对象去设置:

// "myAwesomeDropzone" 是谁人 HTML 元素的 ID
// 这里的id不是驼峰花样,是以`-`为分开,如 id="my-awesome-dropzone"
Dropzone.options.myAwesomeDropzone = {
  paramName: "file", // The name that will be used to transfer the file
  maxFilesize: 2, // MB
  accept: function(file, done) {
    if (file.name == "justinbieber.jpg") {
      done("Naha, you don't.");
    }
    else { done(); }
  }
};
要领二:

最显著的体式格局是经由历程一个挑选对象时实例化一个dropzone,以前面手动竖立dropzones的体式格局。

经常使用要领:

因为我们须要运用dropzone供应的一些款式,比方预览时图片款式等,如许就算手动竖立,但也须要运用到dropzone 款式类,那如许就会致使初始化两次,在控制台就会报错,这时刻就须要在手动初始化之前设置以下代码:

// Prevent Dropzone from auto discovering this element:
Dropzone.options.myAwesomeDropzone = false;
// This is useful when you want to create the
// Dropzone programmatically later

// Disable auto discover for all elements:
Dropzone.autoDiscover = false;

例子:

<div class="dropzone" id="myDropzone">
    <div class="am-text-success dz-message">
        将文件拖拽到此处<br>或点此翻开文件治理器挑选文件
    </div>
</div>

<script type="text/javascript">
    Dropzone.autoDiscover = false;
    var myDropzone = new Dropzone("#myDropzone", {
        url: "/file/upload",
        addRemoveLinks: true,
        method: 'post',
        filesizeBase: 1024,
        sending: function(file, xhr, formData) {
            formData.append("filesize", file.size);
        },
        success: function (file, response, e) {
            var res = JSON.parse(response);
            if (res.error) {
                $(file.previewTemplate).children('.dz-error-mark').css('opacity', '1')
            }
        }
    });
</script>

像上面如许,既能运用 dropzone 的款式,也能本身手动初始化上传。

设置选项

参数形貌
url除了form元素之外的其他元素必需指定该参数(或当form元素没有操纵属性)。您还能够供应一个函数,参数为files以及必需返回url(since v3.12.0)
method默以为”post”,必要的时刻你也能够设置为”put”。 您还能够供应一个函数,参数为files以及必需返回这个method(since v3.12.0)
parallelUploads同时上传若干个文件。(更多信息拜见行列文件上传部份)
maxFilesize单元 MB
filesizeBase默许1000。这个定义的基本是不是应当运用1000或1024来盘算文件大小。1000是有效的,因为1000个字节即是1千字节,1024字节= 1 Kibibyte。你能够转变成1024,假如你不在乎的有效性。
paramName文件上传后端吸收的参数名。默许file。注重:假如你设置uploadMultiple为true,那末Dropzone会将[]附加到这个名字,也就是后端吸收的是一个file[]数组。
uploadMultipleDropzone是不是在一个请求中发送多个文件。假如它设置为true,然后fallback部份的input元素须有multiple属性。这个选项也会触发其他事宜(如processingmultiple)。有关更多信息,请拜见事宜部份。
headers一个向服务器发送附加头的对象。如:headers: { "My-Awesome-Header": "header value" }
addRemoveLinks这将增加一个链接到每一个文件,删除或作废预览文件(假如已上传)。dictCancelUpload, dictCancelUploadConfirmation and dictRemoveFile三个参数可选。
previewsContainer定义文件预览显现。假如为null就运用 Dropzone 默许的。能够运用一段一般的html元素或css挑选器。被挑选的html元素必需包含dropzone-previews款式类确保预览显现一般。
clickable假如为true,dropzone元素本身将是可点击的,假如false将不可被点击。别的,还能够是一段一般的html或许css挑选器,示意点击该元素触发资源治理器。
createImageThumbnails
maxThumbnailFilesize单元 MB。文件名凌驾这个极限时,缩略图将不会天生。
thumbnailWidth假如为null,将运用图象的比例来盘算它。
thumbnailHeightthumbnailWidth一样。假如二者都是null,图象将不会调解。
maxFiles假如不为null,定义若干个文件将被处置惩罚。假如凌驾,事宜maxfilesexceeded将被挪用。相应地dropzone元素获得了类dz-max—files-reached,因而你能够供应视觉反应。
resize竖立调解信息时被挪用的函数。file作为函数第一个参数,同时必需返回一个对象包含srcX, srcY, srcWidthsrcHeight 和雷同的 trg*。这些值将被用于ctx.drawImage()函数。
initDropzone初始化时挪用的函数。你能在这个函数中设置事宜侦听器。
acceptedFiles accept函数默许的完成函数,用于搜检文件的mime范例或扩大。这是一个逗号分开的mime范例和文件扩大名的数组。如。image/*,application/pdf,.psd。假如Dropzone是clickable,此选项将被用作accept函数的参数输入。
accept一个吸收filedone函数作为参数输入的函数。假如done函数挪用无参数,文件会被处置惩罚。假如你在done函数中传入了参数(比方毛病信息)文件将不会被上传。假如文件太大或不婚配的mime范例这个函数不会挪用。
autoProcessQueue当设置为false,你必需本身挪用myDropzone.processQueue()上传文件。有关更多信息,请拜见下面有关处置惩罚行列。
previewTemplate一个字符串,个中包含模板用于每一个图象。转变它满足你的需求,但确保准确地供应统统元素。你能够在页面中竖立如许一个容器:id="preview-template"(设置style=”display: none;”),然后如许设置:previewTemplate: document.querySelector('preview-template').innerHTML
forceFallback默许值为false。假如为true,fallback将被强行运用。这是异常有效的测试服务器完成主要体式格局,确保统统如预期所想,并测试你的fallback显现怎样。
fallback当浏览器不支撑时挪用的函数。默许完成显现了fallback内的input域并增加一个文本。
为自定义的 dropzone,你也能够运用以下这些选项
dictDefaultMessage任何文件被拖拽进地区之前显现的信息。这通常是被一个图象,但默以为“Drop files here to upload”。
dictFallbackMessage假如浏览器不支撑,默许音讯将被替代为这个文本。默以为“Your browser does not support drag’n’drop file uploads.”。
dictFallbackText这将被增加在input file之前。假如你供应一个fallback元素,或许该选项为空该选项将被疏忽。默以为“Please use the fallback form below to upload your files like in the olden days.”。
dictInvalidFileType假如文件范例不婚配时显现的毛病音讯。
dictFileTooBig当文件太大时显现。{{filesize}}` 和 {{maxFilesize}}` 将被替代。
dictResponseError假如服务器相应是无效的时显现的毛病音讯。{{statusCode}}` 将被替代为服务器端返回的状况码。
dictCancelUpload假如addRemoveLinks为true,文本用于作废上传链接的笔墨。
dictCancelUploadConfirmation假如addRemoveLinks为true,文本用于作废上传的笔墨。
dictRemoveFile假如addRemoveLinks为true,用于删除一个文件的文本。
dictMaxFilesExceeded假如设置了maxFiles,这将是凌驾了设置的时刻的毛病音讯。

你也能够掩盖统统违约事宜行动选项。假如你供应的drop选项能够掩盖默许的事宜处置惩罚顺序。你应当熟习代码,因为您能够轻松控制如许的上传。假如你只是想做分外修改,比方增加一些过滤什么的,能够监听事宜

文件上传行列

当一个文件被增加到dropzone,其status被设置到Dropzone.QUEUED(accept函数搜检经由历程后),这意味着该文件如今在行列中。

假如你能够挑选autoProcessQueue设置为true,那末行列是马上处置惩罚,文件被删除或一个上传完成后,经由历程挪用.processQueue(),搜检有若干文件正在上传,假如它少于option.parallelUploads,.processFile将被挪用。

假如你autoProcessQueue设置为false,那末.processQueue()不会被隐式地挪用。这意味着当你想上传现在行列中统统文件时你必需本身挪用它。

规划

为每一个文件天生预览HTML,设置dropzone定义的选项previewTemplate,默以为:

<div class="dz-preview dz-file-preview">
  <div class="dz-details">
    <div class="dz-filename"><span data-dz-name></span></div>
    <div class="dz-size" data-dz-size></div>
    <img data-dz-thumbnail />
  </div>
  <div class="dz-progress"><span class="dz-upload" data-dz-uploadprogress></span></div>
  <div class="dz-success-mark"><span>✔</span></div>
  <div class="dz-error-mark"><span>✘</span></div>
  <div class="dz-error-message"><span data-dz-errormessage></span></div>
</div>

当文件在上传历程当中的时刻,dz-preview中的dz-processing将被显现;当文件上传以后dz-success将被显现;假如文件上传毛病或没网dz-error将被显现,此时data-dz-errormessage的内容将是服务器端返回的信息。

重写默许的模板,便能够够运用设置中的previewTemplate选项。

您能够经由历程file.previewElement接见文件的HTML预览,而且设置任何事宜。如:

success: function (file, response, e) {
    var res = JSON.parse(response);
    if (res.error) {
        $(file.previewTemplate).children('.dz-error-mark').css('opacity', '1')
    }
}

假如你想打破常规重写previewElement,能够在你想要的元素上增加data-dz-*属性:

  • data-dz-name

  • data-dz-size

  • data-dz-thumbnail (这个必需是 <img /> 元素,然后该元素的 altsrc 属性会被 Dropzone 自动转变成相应的值)

  • data-dz-uploadprogress (当文件处于上传历程当中的时刻Dropzone 将转变此元素的 style.width 的值,从 0% 到 100%)

  • data-dz-errormessage
    Dropzone将寻觅这些元素,并转变默许选项和更新它的内容。

假如你想要一些特定链接删除一个文件(而不是建于addRemoveLinks设置),您能够简朴地插进去元素的模板data-dz-remove属性。

<img src="removebutton.png" alt="Click me to remove the file." data-dz-remove />

你也不必被这些运用通例所强制。假如你完整掩盖统统默许事宜监听器能够从头最先重修你的规划。

假如你想让你的dropzone看起来像官方页面那样,运用装置部份供应的增加款式表和spritemaps即可。

看到主题部份,看看怎样转变Dropzone 的UI。

官方竖立了一个例子,设置几行代码,让Dropzone看起来和以为完整和jQuery文件上传差不多。Check it out!

Dropzone要领

假如你想删除已增加的文件,你能够挪用.removeFile(file)。这类要领也触发removedfile事宜。

下面是一个示例,文件上传完成后将自动删除:

myDropzone.on("complete", function(file) {
  myDropzone.removeFile(file);
});

假如你想删除所以的文件,简朴地运用.removeAllFiles()。正在上传中的文件不会被删除。假如你想作废正在上传的文件,挪用.removeAllFiles(true)将作废上传。

假如你设置了autoProcessQueuefalse,你必需挪用.processQueue()完成上传。

接见dropzone中的统统文件,运用myDropzone.files

  • 统统可接收的文件:.getAcceptedFiles()

  • 所以被谢绝的文件:.getRejectedFiles()

  • 行列中的统统文件:.getQueuedFiles()

  • 上传中的统统文件:.getUploadingFiles()
    假如不在须要一个dropzone,运用当前示例挪用.disable(),这将移除该元素上的事宜、文件。从新激活运用.enable()。`

假如你不喜欢浏览器默许的confirm,您能够经由历程掩盖Dropzone.confirm处置惩罚它们:

Dropzone.confirm = function(question, accepted, rejected) {
  // Ask the question, and call accepted() or rejected() accordingly.
  // CAREFUL: rejected might not be defined. Do nothing in that case.
};

事宜

Dropzone触发事宜在处置惩罚文件时,你能够经由历程当前实例挪用.on(eventName, callbackFunction)监听事宜。

因为听事宜只能是Dropzone实例,设置你的事宜侦听器,最好的处所是在init函数。

Dropzone.options.myAwesomeDropzone = {
  init: function() {
    this.on("addedfile", function(file) { alert("Added file."); });
  }
};

假如你手动竖立dropzones,你能够设置实例的事宜监听器,就像如许:

// This example uses jQuery so it creates the Dropzone, only when the DOM has
// loaded.

// Disabling autoDiscover, otherwise Dropzone will try to attach twice.
Dropzone.autoDiscover = false;
// or disable for specific dropzone:
// Dropzone.options.myDropzone = false;

$(function() {
  // Now that the DOM is fully loaded, create the dropzone, and setup the
  // event listeners
  var myDropzone = new Dropzone("#my-dropzone");
  myDropzone.on("addedfile", function(file) {
    /* Maybe display some more file information on your page */
  });
})

这是更庞杂的,没有必要的,除非你有一个很好的理由来治理实例化Dropzones。

Dropzone本身严峻依靠事宜,视觉上的展现都是经由历程监听去做的。这些事宜监听器设置在每一个Dropzone的默许设置,能够掩盖,从而庖代默许的行动完成本身的事宜回调。

事宜列表

不掩盖这些设置选项,除非你晓得你在做什么。
事宜形貌
统统这些吸收event作为第一个参数
drop用户松放文件到到dropzone
dragstart用户最先拖动文件到任何处所
dragend拖动完毕
dragenter用户拖拽文件到Dropzone
dragover用户拖动一个文件经由Dropzone
dragleave用户拖动一个文件脱离Dropzone
统统这些吸收file作为第一个参数
addedfile当一个文件被增加到列表中
removedfile从列表中删除一个文件。你能够监听该事宜然后从您的服务器删除文件
thumbnail天生缩略图。吸收dataUrl作为第二个参数
error发作一个毛病。吸收errorMessage作为第二个参数,假如毛病是因为XMLHttpRequest xhr对象为第三个参数。
processing当一个文件被处置惩罚(因为行列不会马上处置惩罚统统文件)。这个事宜在processingfile之前被触发。
uploadprogress每当文件上载历程变化是触发。取得progress作为第二个参数,是一个百分比(0 – 100)和bytesSent作为第三个参数,是已发送到服务器的字节数目。当上传完成dropzone确保uploadprogress为100%并被挪用一次。Warning:这个函数能够挪用屡次运用雷同的progress
sending在每一个文件发送是触发。file为第一个参数,xhr对象和formData对象作为第二个和第三个参数,你能够修改它们(比方增加CSRF令牌)或增加分外的数据。
success文件已胜利上传触发。file为第一个参数,猎取服务器相应作为第二个参数。(这一事宜在finished之前触发。
complete上传胜利或毛病时。
canceled当一个文件上传被作废时。
maxfilesreached文件数目接收抵达maxFiles极限时
maxfilesexceeded每一个文件被谢绝了,因为文件的数目凌驾了maxFiles极限时触发
统统这些收到的files作为第一个参数,而且就当uploadMultipletrue时触发
processingmultipleprocessing的形貌。
sendingmultiplesending的形貌。
successmultiplesuccess的形貌。
completemultiplecomplete的形貌。
canceledmultiplecanceled的形貌。
特别事宜
totaluploadprogress触发时包含参数total uploadProgress(0 - 100),totalBytestotalBytesSent。这个事宜能够用来显现统统文件的团体上载进度
reset挪用时列表中的统统文件被删除,dropzone重置为初始状况。
queuecomplete当行列中的统统文件上传完成时。

主题

假如你想对Dropzone的主题完整自定义,在大多数情况下,您能够简朴地庖代HTML模板预览,调解CSS,也能够竖立一些分外的事宜监听器。

官方竖立了一个例子,设置几行代码,让Dropzone看起来和以为完整和jQuery文件上传差不多。Check it out!。正如您能够看到的,最大的变化就是previewTemplate。然后增加了一些分外的事宜监听器来让它看起来相符本身的请求。

但是,您能够完整从头最先完成您的UI。

掩盖默许的事宜监听器,竖立您本身的自定义Dropzone,能够如许:

// This is an example of completely disabling Dropzone's default behavior.
// Do *not* use this unless you really know what you are doing.
Dropzone.myDropzone.options = {
  previewTemplate: document.querySelector('#template-container').innerHTML,
  // Specifing an event as an configuration option overwrites the default
  // `addedfile` event handler.
  addedfile: function(file) {
    file.previewElement = Dropzone.createElement(this.options.previewTemplate);
    // Now attach this new element some where in your page
  },
  thumbnail: function(file, dataUrl) {
    // Display the image in your file.previewElement
  },
  uploadprogress: function(file, progress, bytesSent) {
    // Display the progress
  }
  // etc...
};

上面的这些代码明显缺少现实的完成。看源代码,看看Dropzone内部的完成。

假如你不须要任何默许Dropzone UI,只对Dropzone的事宜处置惩罚顺序、文件上传和拖拽功用感兴趣,那你应当运用以上选项事宜处置惩罚。

Tips

假如你不想要默许音讯提醒(拖拽文件上传(或单击)),您能够在你dropzone元素内增加一个元素包含类dz-message,如许dropzone就不会为您竖立的音讯。

Dropzone 或提交你设置的form内的统统隐蔽的表单域信息。所以当你是运用form元素的情势的话,这是一个简朴的要领来提交分外的数据,至因而get照样post取决于你formmethod。固然也能够在js设置中增加其他的参数。

当事宜绑定完成以后,Dropzone 会增加数据到file对象。假如是image的话,你能够经由历程file.widthfile.height接见到图片的宽度和高度。而且file.upload对象会包含以下信息:progress (0-100), total (总字节) and bytesSent(已上传字节)。如许你能够经由历程这写信息自定义上传进度条等。

假如你想给上传的文件增加分外(多个文件时会详细到每一个文件),您能够注册发送事宜:

myDropzone.on("sending", function(file, xhr, formData) {
  // Will send the filesize along with the file as POST data.
  formData.append("filesize", file.size);
});

文件上传以后,能够经由历程file.previewElement接见上传后文件的预览html。比方:

myDropzone.on("addedfile", function(file) {
  file.previewElement.addEventListener("click", function() {
    myDropzone.removeFile(file);
  });
});

假如你想全部的body都是一个Dropzone实例而且在某个处所显现文件预览,那你能够简朴地为body实例化一个Dropzone对象,提醒定义previewsContainer 选项。这个previewsContainer能够是dropzone-previewsdropzone类,以便准确显现文件预览:

new Dropzone(document.body, {
  previewsContainer: ".dropzone-previews",
  // You probably don't want the whole body
  // to be clickable to select files
  clickable: false
});

能够在github wiki寻觅更多的例子。

兼容性

本节形貌Dropzone兼容浏览器和旧版本。

浏览器支撑:

  • Chrome 7+

  • Firefox 4+

  • IE 10+

  • Opera 12+ (MacOS V12版本没法运用,因为它的API有题目)

  • Safari 6+

关于统统其他浏览器,dropzone供应一个版的文件输入回退。
在老式浏览器中拖放是没有解决方案,毕竟它不支撑嘛~~,其次dropzone的图片预览也是一样的原理。
然则,用户运用老式浏览器照样能够上传文件滴,只是看起来和以为起来都不是很棒。
哎,年代已不属于它们了。

Version 4.0

这不是一个更新日记。只列出兼容性题目。

  • 转变默许previewTemplate。规划做了新调解layout sectin.

  • 运用SVG替代PNG spritemap(CSS文件如今唯一须要包含的附加文件)

Version 3.0

这不是一个更新日记。只列出兼容性题目。

Version 2.0

这不是一个更新日记。只列出兼容性题目。

从2.0版本最先,Dropzone不再依靠jQuery,假如运用了jQuery,Dropzone 经由历程jQuery模块的情势加载本身。
这意味着竖立Dropzones如许仍能事情:

$("#my-dropzone").dropzone({ /* options */ });

假如你经由历程一般组织函数的情势竖立Dropzones,你必需经由历程原始HTMLElement,或许一个挑选器字符串挑选相应的元素,如许该版本才运转:

// With jQuery
new Dropzone($("#my-dropzone").get(0));
// Without jQuery
new Dropzone("#my-dropzone");
new Dropzone(document.querySelector("#my-dropzone"));

别的一个转变就是,Dropzone不再存储实例内部元素的数据属性。为了获得一个dropzone元素如许做:

// DEPRECATED, do not use:
$("#my-dropzone").data("dropzone"); // won't work anymore
// Do this now:
Dropzone.forElement(element); // Providing a raw HTMLElement
// or
Dropzone.forElement("#my-dropzone"); // Providing a selector string.

About me

博客: http://blog.helloarron.com
Github: https://github.com/ArronYR
Email: yangyun4814@gmail.com

因为英语不好,花了一天的时候才完成,让人人见笑了。有许多处所都不完美,还望人人指出修改,假如你以为这个对你有效,还请点个“引荐”,感谢!

    原文作者:Arron_yr
    原文地址: https://segmentfault.com/a/1190000004045240
    本文转自网络文章,转载此文章仅为分享知识,如有侵权,请联系博主进行删除。
点赞