dropzonejs中文翻译手册 DropzoneJS是一个提供文件拖拽上传并且提供图片预览的开源类库.

时间：2021-05-15 23:11:09

http://wxb.github.io/dropzonejs.com.zh-CN/dropzonezh-CN/

由于项目需要，完成一个web的图片拖拽上传，也就顺便学习和了解了一下前端的比较新的技术：HTML5的api，作为一名前端的菜鸟，没什么可说的，直接分享自己学习的资料：

关于HTML5 的这些新的特性大家可以到Mozilla的开发者社区MDN https://developer.mozilla.org/zh-CN/ 上查HTML5的资料

还有就是发掘到的比较牛逼的一篇博客：http://blog.bingo929.com/renren-drag-drop-photo-filereader-formdata.html

实现图片拖拽上传需要用到那些技术？

拖拽上传应用主要使用了以下HTML5技术：

Drag&Drop : HTML5基于拖拽的事件机制.

File API : 可以很方便的让Web应用访问文件对象，File API包括FileList、Blob、File、FileReader、URI scheme，本文主要讲解拖拽上传中用到的FileList和FileReader接口。

FormData : FormData是基于XMLHttpRequest Level 2的新接口，可以方便web应用模拟Form表单数据，最重要的是它支持文件的二进制流数据，这样我们就能够通过它来实现AJAX向后端发送文件数据了。

菜鸟的尴尬！

作为一个前端菜鸟，公司能给你4、5个小时调查实现所需要的技术已经很慷慨了。所以你想要对领导说：我要学习这个学习那个然后才能做。 呵呵，那是不可能的。现在的公司做的都是敏捷开发，讲求的是效率、成本控制，所以不会给你时间学会在来做东西的。那么怎么办？ 我们强大的js有着丰富的插件，使用这些类库各方面来说都要比自己写的要好，至少CSS不用自己考虑太多，而且功能上比自己写的要好很多，毕竟时间有限，功力还不够。只能设想找个时间学习这些底层的技术，将来可以自己写。好了！说说今天的插件Dropzonejs

翻译初衷？

其实也算不上翻译，只是这个类库很小，自己在看官方手册的时候忽然想着，看英文总是觉得有点慢，但是开发的过程中我们需要反复查找手册，学习手册。这样还不如在我第一次通读手册时，一边读一边写下翻译，就这样有了这个翻译的手册，全凭理解和翻译工具。可能会有一些理解错误的地方，但是无论怎样也算是有了一个自己整理的手册了，上周项目完成了，今晚闲着就把这些整理出来，分享个大家

DropzoneJS是什么？

DropzoneJS是一个提供文件拖拽上传并且提供图片预览的开源类库，它是轻量级的，不依赖任何其他类库（如JQuery）并且高度可定制.

DropzoneJS相关信息

官网：http://www.dropzonejs.com/

GitHub：https://github.com/enyo/dropzone

DropzoneJS中文手册

地址：http://wxb.github.io/dropzonejs.com.zh-CN/

这个手册是我把官网copy了一份，然后制作的一个静态的手册

好了，很简单的一个js类库，大家有需要了可以对看看我翻译的中文，如果我的翻译有什么错误可以留言或者在GitHub:https://github.com/wxb/dropzonejs.com.zh-CN 上issue

新闻

我刚刚发布 Dropzone v4.0.0! 它已经完全重新设计, 并已更新的网站. 非常感谢 1910 设计新的 logo 和网站. 它看起来非常棒. 看看他们的工作!

我在 COLORGLARE 上最新的文章: Stop writing stateful HTML. 如果你对我的工作感兴趣，请订阅我的 RSS 源.

我的乐队, Gin Ga, 最近发布了一张新专辑 ! 它叫做«YES / NO» 已经可以在 Spotify 和 iTunes商店下载. 你可以看到我们 在 youtube 上最新的视频剪辑.

安装

你也许只要看一下这个 简单示例 (源代码) 就可以开始. 继续一步一步学习下面的知道和不同的安装方法.

下载单独的 dropzone.js 并像下面这样在文件中引入:

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

现在,Dropzone 已经被激活，用window.Dropzone来使用.

Dropzone 不会 处理你上传到服务器上面的文件. 你必须自己编写代码实现接受和保存上传的文件. 请参考 服务器端实现部分的详细信息.

这是你需要运行dropzone上传代码的所有工作, 但是如果你想要让你的dropzone拥有和本页面上的dropzone一样的效果, 你就需要从 dist 文件夹中下载样式文件 dropzone.css.

使用组件

如果你要使用 组件 你只需要添加 dropzone 作为一个依赖:

"enyo/dropzone": "*"

然后就像下面这样引入:

var Dropzone = require("dropzone");

这样他就被激活了并自动扫描文档.

基础的CSS样式也被包含在组件中, 但是如果你想让它看起来和本页一样, 你就必须现在CSS文件 (见下文).

使用 RequireJS

Dropzone is also available as an AMD module for RequireJS.

You can find the dropzone-amd-module in the downloads folder.

用法

使用dropzone的典型方式是通过创建一个 class 属性中包含 dropzone 的form 表单元素 :

<form action="/file-upload"

      class="dropzone"

      id="my-awesome-dropzone"></form>

就是这么简单，Dropzone将查找所有的 class 属性中包含 dropzone 的表单元素, 的表单元素，自动地把自己加入到表单元素上，并且拖拽进的这些上传文件将被发送到 action 这个特殊的参数. 这些上传文件将被正常处理就像这里是一段像下面这样的HTML代码:

<input type="file" name="file" />

如果你想使用其他的名字来替换 file 你可以在 configure dropzone 中设置选项 paramName.

如果你正在使用组件，别忘记 require("dropzone"); 否则他将不会被激活.

如果你想要你的文件上传正确工作，甚至在没有JavaScript环境中, 你可以引入一个 class是 fallback的元素, 在浏览器支持的情况下, dropzone会删除这个元素 . 如果浏览器不支持, Dropzone 将不会删除 fallback 元素,前提是你提供了这个元素. (显然, 如果浏览器不支持JavaScript,form将保持原来的样子)

通常会看起来像这样:

<form action="/file-upload" class="dropzone">

  <div class="fallback">

    <input name="file" type="file" multiple />

  </div>

</form>

程序化的方式创建 dropzones

或者你可以程序化方式创建 dropzones (甚至不在 form 元素上) 通过初始化一个 Dropzone 类对象

// Dropzone class:

var myDropzone = new Dropzone("div#myId", { url: "/file/post"});

或者如果您使用 jQuery，您可以使用 Dropzone 附带的 jQuery 插件:

// jQuery

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

不要忘记指定url选项如果您不使用窗体元素，因为 Dropzone 不知道在哪儿发布到无action属性.

服务器端实现

Dropzone 并不提供服务器端实现的处理文件，但是文件的方式都是上传就等于像这样简单的文件上传表单:

<form action="" method="post" enctype="multipart/form-data">

  <input type="file" name="file" />

</form>

若要处理服务器上的基本文件上传，请看看相应的文件中的处理方法。这里只提供了一些，如果你认为我应该添加一些，请与我联系.

付费文档:

请如果您需要更多的信息看Dropzone FAQ.

配置

这里有两种方式配置 dropzones.

最明显的方式是通过程序化的方法实例化一个dropzone 对象, 就像上一节 create dropzones programmatically看到的一样.

但是如果你仅仅使用一个class是 dropzone的HTML元素, 不想以程序化的方式实例化一个对象, 所以你就必须在某个地方保存配置信息以便让 Dropzone 实例化dropzones的HTML元素时知道如果配置它们.

通过使用 Dropzone.options 对象.

// "myAwesomeDropzone" is the camelized version of the HTML element's ID

  // "myAwesomeDropzone" 是dropzone的HTML元素ID的驼峰命名

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 行为, 你也可以在每个元素基础或在一般全局上禁用它:

// Prevent Dropzone from auto discovering this element:

  // 阻止 Dropzone 自动寻找这个元素:

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;
配置项
选项 描述
url 必须被设置,当dropzone在 form 表单以外的元素上时[译者注:dropzone不一定要在form元素上，也可以在一个div上，这里的意思就是假如在一个div上时必须设置URL](或者form表单没有 action 属性). 你也可以提供一个被 files调用的函数 并且必须返回 url (从 v3.12.0开始)
method 默认"post" 如有必要也可以修改成 "put" . 你也可以提供一个被 files调用的函数 并且必须返回 method (since v3.12.0)
parallelUploads 有多少文件将上载到并行处理 (见 进行排队文件上传 部分获取更多信息)[译者注：本人在使用过程发现：当使用手动上传时，每次只能上传两个文件，这样需要多次点击才能实现所有上传，最后学习了一下 Enqueuing file uploads 里面的关于自动上传时的处理流程，设置了这里的参数时，才能一下子全部队列上传]
maxFilesize 以MB为单位[译者注：上传文件的大小限制]
filesizeBase 默认值为 1000. 这个选项将设置在计算文件大小时使用 1000 还是使用 1024作为基本单位. 1000 是正确的, 因为 1000 Bytes 等于 1 Kilobyte, 1024 Bytes 等于 1 Kibibyte. 如果你不在乎有效性，您可以更改这个选项为 1024 .
paramName 设置传输文件名称参数. 默认是 file. 注意: 如果你将配置项 uploadMultiple 设置为 true, 那么 Dropzone 将在paramName设置的name的后面追加 [].
uploadMultiple 是否 Dropzone 应该在一个请求中发送多个文件. 如果此设置为 true，然后fallbach 中 input 的元素将具有multiple属性. 此选项还会触发其他事件 (如 processingmultiple). 请参阅事件部分了解更多信息.
headers 要向服务器发送的其他头文件的对象. 例如: headers: { "My-Awesome-Header": "header value" }
addRemoveLinks 在每个预览文件下面添加一个remove[删除]或者cancel[取消](如果文件已经上传)上传文件的链接[译者注：这里的删除和取消只是从上传队列中取消了，并没有在服务器上删除]. dictCancelUpload, dictCancelUploadConfirmation 和 dictRemoveFile 这三个配置项用来自定义设置相应操作链接的显示文字.[本项设置时布尔值，true开启/false关闭]
previewsContainer 定义文件预览显示位置， 定义为 null 时， 将会消失在Dropzone 元素中. 可以设置成一个HTML元素或者一个CSS选择器. 这个元素的class中应该包含dropzone-previews 以便正确显示预览.
clickable 若果设置 true, dropzone 元素本身将可以点击, 如果设置 false dropzone没有地方可供点击. 否则你也可以通过一个HTML元素，一个CSS选择器（多个HTML元素）或者其他的数组.
createImageThumbnails  
maxThumbnailFilesize 以MB为单位[译者注：也可以使用小数]. 当文件名[译者注:这问是filename，但是测试后发现应该是出错了这里应该是指文件大小]超出这里的设置, 将不会生成缩略图.
thumbnailWidth 默认 null, 设置缩略图的缩略比[译者注：设置width，配合下面的thumbnailHeight一起使用].
thumbnailHeight 就像 thumbnailWidth一样. 如果为空, 将不能重置尺寸.
maxFiles 如果不为 null ，这里设置 Dropzone 最多可以处理多少文件. 如果超过这个限制, maxfilesexceeded 事件将被调用. dropzone 将通过 class 为dz-max- files-reached 反馈一些信息给你.
resize is the function that gets called to create the resize information. It gets the file as first parameter and must return an object with srcX, srcY, srcWidth and srcHeight and the same for trg*. Those values are going to be used by ctx.drawImage().
init Dropzone初始化时调用的函数，你可以在这个方法中设置时间监听.
acceptedMimeTypes 已经废弃， 使用acceptedFiles代替
acceptedFiles accept实现检查文件的 mime 类型或扩展名， 使用逗号分隔文件类型或者扩展名列表. 例如 Eg.: image/*,application/pdf,.psd. 如果 Dropzone 是 clickable[译者注：即配置项clickable是true], 本项将被用作 accept 的参数，就和在 隐藏的 file input 一样.
accept 使用一个 file 和一个done 函数 作为参数的函数. 如果不带参数调用 done 函数时，将处理该文件. 如果你显示一条错误信息，该文件将不会被上传. 如果文件太大或不匹配的 mime 类型，将不调用此函数.
enqueueForUpload 已废弃，被 autoProcessQueue取代.
autoProcessQueue 当设置 false 你必须自己像这样 myDropzone.processQueue() 的调用来上传队列中的上传文件. 请参阅下面有关处理队列的详细信息.
previewTemplate 是一个包含预览dropzone上传的每个文件的模板字符串. 更改它以满足您的需求，但请务必提供正确的所有元素. You can 在你的页面中包含 <div id="preview-template" style="display: none;"></div> 这样的HTML容器, 并且像这样设置: previewTemplate: document.querySelector('preview-template').innerHTML.
forceFallback 默认 false. 如果设置true 将强制使用 fallback .这在测试你的服务器端实现和确保一切如你预期的一样正常工作在没有使用dropzone的情况下，防止你一些经验上的错误，同时可以给你展示fallbacks是怎样显示的 .
fallback 这是一个方法，当浏览器不支持的时候调用. 默认实现展示 fallback input 字段 和一段文本.
若要翻译 dropzone，还可以提供这些选项：
dictDefaultMessage 获取显示之前的任何文件被删除的消息。这通常是由图像，但默认为"Drop files here to upload"所取代
dictFallbackMessage 如果浏览器不受支持，此文本将替换默认的消息。默认值为"Your browser does not support drag'n'drop file uploads."
dictFallbackText 这点文本将在 file input元素选择文件前显示 . 如果你自己提供了 fallback 元素, 或者本项设置成 null 这段文本将被忽略. 默认是 "Please use the fallback form below "
dictInvalidFileType 如果该文件与文件类型不匹配所示的错误消息.
dictFileTooBig 当显示该文件太大。{{filesize}} 和 {{maxFilesize}} 将被替换.
dictResponseError 如果服务器响应无效时的错误消息。{{statusCode}}将被替换的服务器状态代码
dictCancelUpload 如果addRemoveLinks为 true，这段文本用来设置取消上载链接的文本
dictCancelUploadConfirmation 如果addRemoveLinks为 true，这里设置的文本将用于确认取消上载时显示.
dictRemoveFile 如果addRemoveLinks为 true，这段文本用来设置删除文件显示文本.
dictMaxFilesExceeded 如果设置了maxFiles ，这里设置的文本将在文件超出maxfiles设置值时显示.

您也可以重写所有的选项中的默认事件操作. 所以如果您提供选项 drop 你可以重写默认的 drop 事件处理. 如果你打算这样做，那么你应该对这些代码有所熟悉，因为你可以很容易打断上传程序 如果你仅仅想要做像在这里或者哪里添加一些 class, 那么添加事件侦听器 是最好的方法!

队列文件上传

当一个文件被添加到 dropzone 时, 它的 status 就被设置成了 Dropzone.QUEUED (前提是已经通过了 accept 函数的检查) ,这就意味着这个文件已经在上传队列中了.

如果你设置了选项 autoProcessQueue 为 true, 然后队列就会被立即处理, 在文件拖放到zone或者上传完成后, 调用 .processQueue() 来检查当前有多少文件正在被上传, 如果它的值[译者注：processQueue()返回的文件数] 小于 options.parallelUploads的设置值时, 就会调用.processFile(file).

如果你设置 autoProcessQueue 为 false, 那么 .processQueue() 方法是不会被隐式调用的. 这意味着你必须在你想要上传队列中的所有文件时，自己去调用这个方法[译者注：这是很有用的，当我们使用点击按钮上传时，我们就可以设置这里为false，同时我们也应该清楚：这里的手动上传和上面所说的自动上传的实现逻辑是一样的，只是这里我们让程序不去自动上传； 所以在前面说到的关于，多个文件点击上传时每次只能同时上传两个，需要很多次点击，如果我们要一次点击上传全部，我们就应该理解上面自动提交时的逻辑，设置options.parallelUploads，这是本人使用时发现的问题].

布局

这是用选项previewTemplate定义的一段用来显示每个dropzone上传文件预览的HTML代码 ，其默认HTML是这样的:

<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 是文件上传成功时显示 and dz-error 是文件没有上传时显示样式. 最后一个, data-dz-errormessage 将包含服务器返回的文本信息.

想要重写默认的模板, 使用配置项 previewTemplate config.

你可以在任何事件中访问文件预览的HTML 通过使用 file.previewElement.

如果你决定从零开始重新 previewTemplate , 你应该在里面放上用data-dz-*参数定义的元素 :

  • data-dz-name
  • data-dz-size
  • data-dz-thumbnail (这里必须是一个 <img /> 元素 ，并且alt 和 src 属性将被 Dropzone改变)
  • data-dz-uploadprogress ( 当这里有一个 uploadprogress事件时， Dropzone 将更改 style.width 属性从 0% 到 100% )
  • data-dz-errormessage

Dropzone 的默认选项将寻找这些元素，并为它更新的内容.

如果你想要一些特殊的链接来删除文件(而不是使用内置的 addRemoveLinks配置 ), 你可以简单地在模板中插入一个属性值是 data-dz-remove 的HTML元素. 例如:

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

并不强制要求你去配置修改这些，如果你重写了所有的默认事件侦听器，你完全可以从零开始重建你的布局.

如果你想让你的dropzone看起来和本页显示一样的效果，应该如何添加样式表和脚本？请参阅安装部分.

请参阅Theming部分 较为深入看看如何改变 Dropzone 的用户界面.

我创建了一个例子，我只是用来几行简单的配置，就让 Dropzone 看起来和感觉起来跟 jQuery 上传文件的方式完全一样. Check it out!

再次, 如果你仍然不清楚某些功能，请去看看 Dropzone FAQ .

Dropzone 方法

如果你想删除已添加到dropzone中的文件，你可以调用 .removeFile(file). 这个方法也可以触发 removedfile 事件.

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

myDropzone.on("complete", function(file) {

  myDropzone.removeFile(file);

});

如果你想删除所有的文件，简单的使用.removeAllFiles()就可以了.这样调用删除文件并不会删除正在被上传的文件. 如果你想要取消正在上传的文件, 调用 .removeAllFiles(true) 将会取消正在上传的文件.

如果你设置 autoProcessQueue 禁用了自动上传, 你需要自己调用.processQueue().

这是很有用的，如果你想显示文件让用户点击确认按钮来上传文件.

若要访问 dropzone 中的所有文件，请使用 myDropzone.files[译者注： 这里的myDropzone指的是dropzone对象，files是下面的这些方法].

要获得

  • 所有接受文件: .getAcceptedFiles()
  • 所有被拒绝的文件: .getRejectedFiles()
  • 所有排队的文件: .getQueuedFiles()
  • 所有上传文件: .getUploadingFiles()

如果你不再需要 dropzone , 只需要dropzone对象上调用 .disable() . 这将移除元素上所有的事件监听, 并且清除所有的文件数组. 若要重启Dropzone使用 .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.

};

事件

当处理文件时触发事件, 你可以通过调用 .on(eventName, callbackFunction) 很容易地在你的 instance[实例]注册事件监听.

事件监听器只能在Dropzone的instances[实例] 上注册 , 添加你的事件监听器最好的地方是 在 init 方法中:

// The recommended way from within the init configuration:

Dropzone.options.myAwesomeDropzone = {

  init: function() {

    this.on("addedfile", function(file) { alert("Added file."); });

  }

};

If you 如果你以程序化的方式创建dropzone, 你可以像下面这样在你的实例上注册事件监听器:

// 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 */

  });

})

这是有点更复杂，也没有必要，除非你有一个好的理由以编程方式实例化dropzone.

Dropzone 本身依赖于事件. 你看到的所以事情都是通过事件监听器完成的. 这些事件侦听在dropzone中都有默认的配置，你可以重写来覆盖这些默认的行为，从而用您自己的事件行为来替换dropzone默认行为.

当你正真的知道dropzone是怎样工作的，当你想要完全主题化你的dropzone行为时，你就应该设置这些事件侦听

事件列表

不要 在配置项中重写这些事件行为, 除非你清楚你在干什么.
参数 描述
所有这些事件都把 event 作为第一个参数:
drop 用户把文件放到dropzone上
dragstart 用户开始拖动文件到任何地方
dragend 拖动结束
dragenter 用户把一个文件拖放到dropzone上
dragover 用户拖动一个文件在dropzone上
dragleave 用户拖动一个文件 Dropzone 外面
下面所有这些都接受 file 作为第一个参数:
addedfile 当文件被添加到上传列表
removedfile 任何时候都可以调用这个方法来从上传列表中删除文件. 如果你想从你的服务器上面删除这个文件就可以利用这个监听方法[译者注：一定要清楚，removefile并不会删除服务器上面的文件，你需要自己实现服务器删除代码] .
thumbnail 当已生成缩略图。接收 dataUrl 作为第二个参数.
error 出错时. 接受 errorMessage 作为第二个参数，并且如果错误是 XMLHttpRequest对象， 那就作为第三个参数.
processing 当一个文件获取处理 （因为不是所有的文件会立即得到处理的队列）。以前，此事件被称为 processingfile.
uploadprogress Gets called periodically whenever the file upload progress changes.

Gets the progress parameter as second parameter which
is a percentage (0-100) and the bytesSent parameter
as third which is the number of the bytes that have been sent to
the server.

When an upload finishes dropzone ensures that
uploadprogress will be called with a percentage of 100 at
least once.

Warning: This function can potentially be called
with the same progress multiple times.
sending

在每个文件被发送前调用. 得到 xhr 对象 和
formData
对象作为第二个和第三个参数, 所以你可以修改他们(add a CSRF token) 或者追加额外的数据.
success 文件已经成功上传，获得服务器返回信息作为第二个参数(这个时间又被称作finished)
complete 当上传完成，成功或者出现错误时调用.
canceled

当取消文件上传式调用

maxfilesreached 当文件的数量达到maxFiles限制时调用.
maxfilesexceeded 由于文件数量达到 maxFiles 限制数量被拒绝时调用.
下面的所有这些接受一个文件列表作为第一个参数，并且仅在 uploadMultiple 设置为true时使用有效:
processingmultiple 查看processing 描述.
sendingmultiple 查看 sending 描述.
successmultiple 查看 success 描述.
completemultiple 查看 complete 描述.
canceledmultiple 查看 canceled 描述.

特殊事件:
totaluploadprogress

用 uploadProgress (0-100),
totalBytes 和 totalBytesSent的总数调用. 此事件可以用于显示所有文件的总体上传进度.
reset 当列表中的所有文件都被删除，并且 dropzone 被重置为初始状态时调用.
queuecomplete 当上传队列中的所有文件上传完成时调用.

主题

如果你想完全自定义你的Dropzone主题, 大多数情况下你可以简单的 替换预览 HTML 模板, 改写你的CSS是适应dropzone, 并且可以创建一些事件监听器.

用这种方法你可以做的更好。 我们创建了一个示例，在这个示例中我让dropzone看起来和感觉上完全和jQuery文件上传一样，而这仅仅是配置了几行代码. 看看它!

你可以看到, 最大的修改是 previewTemplate. 然后，添加几个额外的事件侦听器，使它看起来和参考的完全一样.

你可以从新实现你的用户界面.

当Dropzone被创建时, Dropzone本身会在其上面设置大量的事件侦听器,
来处理你所有的 UI. 他们添加到Dropzone中: 创建一个新的HTML 元素,
添加<img> 元素当提供了图片信息(使用 thumbnail 时间),
当 uploadprogress 事件被触发时,更新上传进度条[译者注：就是进度条会根据上次情况更新上传进度] . 当 success 时间触发时,显示一个选择标记,等等...

所有的 能看到的效果 都是由这些事件处理 完成的. 如果你把它们都重写成一个空函数, Dropzone
仍然会正常工作, 但是你将看不到任何拖着的效果.

如果你喜欢Dropzone默认的效果, 但是仅仅想要在这些地方或者哪些地方添加一些效果, 你应该使用 添加额外的时间侦听器 来代替.

重写默认的事件监听器，来创建你自己的、自定义的Dropzone,
看起来就象这样:

// This is an example of completely disabling Dropzone's default behavior.[这是一个完全禁用Dropzone默认行为的示例]

// 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 事件处理, 文件上传 and 拖放功能.

小贴士

如果你不想使用默认的消息(» 放文件上传 （或单击）«), 你可以用class包含dz-message的HTML元素放到你的Dropzone的HTML元素中 , 这样Dropzone将不会为你创建这条信息.

Dropzone 将提交你放到Dropzone的from中的任何隐藏的字段信息 .所以这是简单的方法来提交额外的数据. 你也可以是使用 params 选项.

Dropzone 将数据添加到您可以使用事件触发时的file 对象. 如果它是一个图像,您可以访问file.width 和 file.height, 就像 file.upload 是一个包含 : progress (0-100), total (总字节数) 和 bytesSent.的对象

如果你想要将其他数据添加到每个文件上传, 你可以注册 sending 事件:

myDropzone.on("sending", function(file, xhr, formData) {

  // Will send the filesize along with the file as POST data.

  formData.append("filesize", file.size);

});

若要访问一个文件的预览 html,您可以访问 file.previewElement. 例如:

myDropzone.on("addedfile", function(file) {

  file.previewElement.addEventListener("click", function() {

    myDropzone.removeFile(file);

  });

});

如果你想要整个页面 body 作为一个Dropzone 并且在一些地方显示这些文件，你可以简单的实例化body作为一个 Dropzone 对象, 定义 previewsContainer 选项. 这个previewsContainer[预览容器] 元素的class应该包含 dropzone-previews 或 dropzone 来显示文件预览.

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 过程中遇到任何问题, 请尝试通过使用 dropzone.js 标记在*.com上找到帮助. 只有当你认为你发现了一个 bug，或者想要建议一个新的功能, 在 Github 上创建一个问题.

兼容性

本节描述与浏览器和 Dropzone 的较早版本的兼容性.

浏览器支持

  • Chrome 7+
  • Firefox 4+
  • IE 10+
  • Opera 12+ (Version 12 for MacOS is disabled because their API is buggy)
  • Safari 6+

对于所有其他浏览器 , dropzone 提供了一个 file input 作为应对策略.

尚无解决方法为较旧的浏览器实现拖 ' 放,它只是不受支持. 对于图片预览也是一样的, 等等... 但使用 dropzone, 您的那些使用较旧浏览器的用户将可以 上传图片. 它只是不会看起来感觉很棒。但是，唉，那是他们的错。

版本 4.0

这不是更新日志。列出了只兼容性问题.

  • 更改默认 previewTemplate. 在layout section新加了一个.
  • Using an already included SVG instead of a PNG spritemap (the CSS file is now the only additional file that you need to include)

版本 3.0

This is not a changelog. Only compatibility problems are listed.

  • All classes are prefixed with dz- now to prevent *ing with other CSS definitions
  • The way previewTemplate is defined has changed. You have to provide data-dz-* elements now
  • If the server returns JSON, it will be parsed for error messages as well
  • There’s a dict* option for all of the visible messages
  • Lots of minor fixes and changes

版本 2.0

This is not a changelog. Only compatibility problems are listed.

Starting with version 2.0, Dropzone no longer depends on jQuery, but Dropzone still registers itself as a jQuery module if available.

That means that creating your Dropzones like this still works:

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

If you create your Dropzones with the normal constructor though, you have to pass either the raw HTMLElement, or a selector string. So those versions all work:

// With jQuery

new Dropzone($("#my-dropzone").get(0));

// Without jQuery

new Dropzone("#my-dropzone");

new Dropzone(document.querySelector("#my-dropzone"));

Another thing that changed, is that Dropzone no longer stores its instances inside the element’s data property. So to get a dropzone for an element do this now:

// 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.

相关文章