摘要：文件上傳后端接收的參數名。定義文件預覽顯示。文件名超過這個極限時縮略圖將不會生成。如果超過事件將被調用。如果為文本用于取消上傳的文字。文件上傳隊列當一個文件被添加到其被設置到函數檢查通過后，這意味著該文件現在在隊列中。

官方文檔：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中：

Dropzone 現在激活和可用,通過window.Dropzone就可以使用了。

Dropzone不處理你的文件上傳在服務器上。你必須自己實現代碼接收和存儲文件。有關更多信息,請參見部分服務器端實現。

完成上面的操作就可以使用 Dropzone ，但是如果你想讓它你上傳的樣式看起來像官方頁面那樣,你需要將下載的dropzones里面的cs發到你的文件夾中并引入。

如果你使用component,你只需添加dropzone依賴：

"enyo/dropzone": "*"

然后這樣引入：

var Dropzone = require("dropzone");

現在它已激活，并可以在頁面中使用。
基本的CSS樣式也包含在組件中，如果你想讓它你上傳的樣式看起來像官方頁面那樣,你需要將下載的dropzones里面的cs發到你的文件夾中并引入。

Dropzone 同樣為RequireJS提供了AMD模塊。

你可以在下載的文件夾中找到dropzone-amd-module。

使用 dropzone 的典型的方式是通過創建一個表單包含與class="dropzone":

就像這樣。dropzone 會通過class為dropzone找到所有的表單元素，并自動將這些元素初始化，然后點擊input選擇文件(或拖拽)之后會根據action指定的地址上傳文件。(其實就和普通的文件上傳沒什么區別，只不過多了個拖拽)

如果你想在后端接受文件的時候用其他的name而不是上面指定的file，您可以配置dropzone的paramName的選項。

如果你是使用component形式，別忘了require("dropzone");,否則是不會生效的。

如果是使用form表單，完成上面的設置之后，就已經可以拖拽上傳了，所以如果你不想在寫一些js去控制上傳中的其他東西，比如進度條、預覽區域等，可以在form內加一個包含fallback類的標簽，dropzone 會自己處理fallback類的標簽區域，當然這是需要瀏覽器支持。如果瀏覽器不支持，那么那就將其作為普通的文件上傳。
這通常是這樣的：

除了直接在form表單中添加class為dropzone讓其自動創建外，還可以在非表單元素上面通過實例化Dropzone類實現。

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

或如果您使用jQuery,您可以使用jQuery插件Dropzone形式：

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

注意：如果你不是使用一個表單元素,別忘了指定一個url選項,因為Dropzone不知道上傳到那里。

Dropzone 不提供的服務器端文件處理的代碼,但是文件上傳的方式是和簡單的表單文件上傳是相同的。比如普通的表單上傳是這樣：

掌握基本的服務器上的文件上傳,請查看各種語言相應的文檔。這里有一些基本的實現文件：

AngularJS and Spring

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。

有兩種方式配置 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;

例子：

    

        將文件拖拽到此處
或點此打開文件管理器選擇文件
    

像上面這樣，既能使用 dropzone 的樣式，也能自己手動初始化上傳。

你也可以覆蓋所有違約事件動作選項。如果你提供的drop選項可以覆蓋默認的事件處理程序。你應該熟悉代碼,因為您可以輕松掌握這樣的上傳。如果你只是想做額外修改,比如添加一些過濾什么的，可以監聽事件。

當一個文件被添加到dropzone,其status被設置到Dropzone.QUEUED(accept函數檢查通過后)，這意味著該文件現在在隊列中。

如果你可以選擇autoProcessQueue設置為true,那么隊列是立即處理,文件被刪除或一個上傳完成后,通過調用.processQueue(),檢查有多少文件正在上傳,如果它少于option.parallelUploads,.processFile將被調用。

如果你autoProcessQueue設置為false,那么.processQueue()不會被隱式地調用。這意味著當你想上傳目前隊列中所有文件時你必須自己調用它。

為每個文件生成預覽HTML，設置dropzone定義的選項previewTemplate,默認為：

  

    

    

    
  
  

  
?
  
?
  

當文件在上傳過程中的時候，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 (這個必須是 元素，然后該元素的 alt 和 src 屬性會被 Dropzone 自動改變為相應的值)

data-dz-uploadprogress (當文件處于上傳過程中的時候Dropzone 將改變此元素的 style.width 的值，從 0% 到 100%)

data-dz-errormessage
Dropzone將尋找這些元素，并改變默認選項和更新它的內容。

如果你想要一些特定鏈接刪除一個文件(而不是建于addRemoveLinks配置),您可以簡單地插入元素的模板data-dz-remove屬性。

你也不用被這些使用慣例所強迫。如果你完全覆蓋所有默認事件監聽器可以從頭開始重建你的布局。

如果你想讓你的dropzone看起來像官方頁面那樣，使用安裝部分提供的添加樣式表和spritemaps即可。

看到主題部分,看看如何改變Dropzone 的UI。

官方創建了一個例子,配置幾行代碼，讓Dropzone看起來和感覺完全和jQuery文件上傳差不多。Check it out!

如果你想刪除已添加的文件,你可以調用.removeFile(file)。這種方法也觸發removedfile事件。

下面是一個示例,文件上傳完成后將自動刪除：

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

如果你想刪除所以的文件，簡單地使用.removeAllFiles()。正在上傳中的文件不會被刪除。如果你想取消正在上傳的文件，調用.removeAllFiles(true)將取消上傳。

如果你設置了autoProcessQueue為false,你必須調用.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的默認配置,可以覆蓋,從而取代默認的行為實現自己的事件回調。

如果你想對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的事件處理程序、文件上傳和拖拽功能感興趣,那你應該使用以上選項事件處理。

如果你不想要默認消息提示(拖拽文件上傳(或單擊)),您可以在你dropzone元素內添加一個元素包含類dz-message，這樣dropzone就不會為您創建的消息。

Dropzone 或提交你設置的form內的所有隱藏的表單域信息。所以當你是使用form元素的形式的話，這是一個簡單的方法來提交額外的數據，至于是get還是post取決于你form的method。當然也可以在js配置中添加其他的參數。

當事件綁定完成之后，Dropzone 會添加數據到file對象。如果是image的話，你可以通過file.width 和 file.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-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兼容瀏覽器和舊版本。

Chrome 7+

Firefox 4+

IE 10+

Opera 12+ (MacOS V12版本無法使用，因為它的API有問題)

Safari 6+

對于所有其他瀏覽器,dropzone提供一個版的文件輸入回退。
在老式瀏覽器中拖放是沒有解決方案，畢竟它不支持嘛~~,其次dropzone的圖片預覽也是同樣的道理。
但是，用戶使用老式瀏覽器還是可以上傳文件滴，只是看起來和感覺起來都不是很棒。
哎,年代已經不屬于它們了。

這不是一個更新日志。只列出兼容性問題。

改變默認previewTemplate。布局做了新調整layout sectin.

使用SVG代替PNG spritemap(CSS文件現在唯一需要包括的附加文件)

這不是一個更新日志。只列出兼容性問題。

這不是一個更新日志。只列出兼容性問題。

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

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

因為英語不好，花了一天的時間才完成，讓大家見笑了。有很多地方都不完善，還望大家指出修正，如果你覺得這個對你有用，還請點個“推薦”，謝謝！