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

新闻

我刚刚发布 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>

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

• NodeJS with express
• Ruby on rails
• Complete PHP tutorial by startutorial.com
• Basic PHP file upload
• Tutorial for Dropzone and Lavarel (PHP) written by Maksim Surguy
• Symfony2 and Amazon S3
• File upload in ASP.NET MVC using Dropzone JS and HTML5

付费文档:

• eBook for Dropzone with PHP by startutorial.com.

请如果您需要更多的信息看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;

您也可以重写所有的选项中的默认事件操作. 所以如果您提供选项 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行为时，你就应该设置这些事件侦听

主题

如果你想完全自定义你的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.