JavaScript 文件拖拽上传插件 dropzone.js 介绍

安装

下载dropzone.js文件并添加到页面中便可。Dropzone 不依赖 jQuery 框架。

启用

能够新建一个div元素，而后经过以下 JavaScript 代码启用 dropzone（若是你使用 jQuery）：

<div id="dropz"></div>
<script>
    $("#dropz").dropzone({
        url: "handle-upload.php",
        maxFiles: 10,
        maxFilesize: 512,
        acceptedFiles: ".js,.obj,.dae"
    });
</script>

若是你没有使用 jQuery 框架，也能够这样来初始化：

<div id="dropz"></div>
<script>
    var dropz = new Dropzone("#dropz", {
        url: "handle-upload.php",
        maxFiles: 10,
        maxFilesize: 512,
        acceptedFiles: ".js,.obj,.dae"
    });
</script>

其中url是必须的值，指明文件上传提交到哪一个页面。其余的值都是可选的，若是使用默认值的话能够省略。

接收文件

Dropzone 并不含任何服务器端的支持和实现，利用 Dropzone 上传文件和利用下面基本的 HTML 表单对于服务器来讲是同样的：

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

配置 Dropzone

此插件的特点就在于很是灵活，提供了许多可选项、事件等。下面分类介绍经常使用的配置项。

功能选项

• url：最重要的参数，指明了文件提交到哪一个页面。
• method：默认为post，若是须要，能够改成put。
• paramName：至关于<input>元素的name属性，默认为file。
• maxFilesize：最大文件大小，单位是 MB。
• maxFiles：默认为null，能够指定为一个数值，限制最多文件数量。
• addRemoveLinks：默认false。若是设为true，则会给文件添加一个删除连接。
• acceptedFiles：指明容许上传的文件类型，格式是逗号分隔的 MIME type 或者扩展名。例如：image/*,application/pdf,.psd,.obj
• uploadMultiple：指明是否容许 Dropzone 一次提交多个文件。默认为false。若是设为true，则至关于 HTML 表单添加multiple属性。
• headers：若是设定，则会做为额外的 header 信息发送到服务器。例如：{"custom-header": "value"}
• init：一个函数，在 Dropzone 初始化的时候调用，能够用来添加本身的事件监听器。
• forceFallback：Fallback 是一种机制，当浏览器不支持此插件时，提供一个备选方案。默认为false。若是设为true，则强制 fallback。
• fallback：一个函数，若是浏览器不支持此插件则调用。

翻译选项

• dictDefaultMessage：没有任何文件被添加的时候的提示文本。
• dictFallbackMessage：Fallback 状况下的提示文本。
• dictInvalidInputType：文件类型被拒绝时的提示文本。
• dictFileTooBig：文件大小过大时的提示文本。
• dictCancelUpload：取消上传连接的文本。
• dictCancelUploadConfirmation：取消上传确认信息的文本。
• dictRemoveFile：移除文件连接的文本。
• dictMaxFilesExceeded：超过最大文件数量的提示文本。

添加事件监听

若是你但愿在一个事件发生时采起一些额外的操做，而不干扰 Dropzone 的默认行为，那么你应该经过添加事件监听器的办法对事件作出响应，而非重写默认事件函数。

重写默认事件函数的例子以下：

$("#dropz").dropzone({
    addedfile: function() {
        // actions...
    }
});

若是你重写默认事件函数，该事件发生时插件默认采起的动做将被覆盖。大多数状况下你仅仅想在事件发生时添加本身的行为，那么应该使用on方法。

jQuery 版本：

$("#dropz").dropzone({
    init: function() {
        this.on("addedfile", function(file) {
            // actions...
        });
    }
});

非 jQuery 版本：

dropz.on("addedfile", function(file) {
    // actions...
});

经常使用事件

如下事件接收 file 为第一个参数

• addedfile：添加了一个文件时发生。
• removedfile：一个文件被移除时发生。你能够监听这个事件并手动从服务器删除这个文件。
• uploadprogress：上传时按必定间隔发生这个事件。第二个参数为一个整数，表示进度，从 0 到 100。第三个参数是一个整数，表示发送到服务器的字节数。当一个上传结束时，Dropzone 保证会把进度设为 100。注意：这个函数可能被以同一个进度调用屡次。
• success：文件成功上传以后发生，第二个参数为服务器响应。
• complete：当文件上传成功或失败以后发生。
• canceled：当文件在上传时被取消的时候发生。
• maxfilesreached：当文件数量达到最大时发生。
• maxfilesexceeded：当文件数量超过限制时发生。

如下事件接收一个 file list 做为第一个参数（仅当uploadMultiple被设为true时才会发生）

• successmultiple
• completemultiple
• cancelmultiple

特殊事件

• totaluploadprogress：第一个参数为总上传进度，第二个参数为总字节数，第三个参数为总上传字节数。

例子

这里我使用上面的选项、事件等写了一个例子，供参考：

<div class="dropz"></div>
<script>
    $(".dropz").dropzone({
        url: "handle-upload.php",
        addRemoveLinks: true,
        dictRemoveLinks: "x",
        dictCancelUpload: "x",
        maxFiles: 10,
        maxFilesize: 5,
        acceptedFiles: ".js",
        init: function() {
            this.on("success", function(file) {
                console.log("File " + file.name + "uploaded");
            });
            this.on("removedfile", function(file) {
                console.log("File " + file.name + "removed");
            });
        }
    });
</script>

外观

Dropzone 下载以后没有自带任何 CSS 样式（人家只有一个 js 文件嘛）。我以为官网提供的 Demo 的外观设计就很是不错，能够供你们参考。

其余教程

Dropzone 的做者在插件的 GitHub Wiki 页面上提供了不少额外教程，很是好，也推荐你们看一看。

这里我只翻译一部分我以为经常使用的教程的标题：

1. 如何显示服务器返回的错误信息？
2. 如何在全部文件上传完毕时获得通知？
3. 如何显示出已经保存在服务器上的文件？
4. 本身实现删除文件时的提示功能
5. 为文件提供自定义缩略图
6. 点击一个按钮再上传全部文件
7. 点击一个按钮删除全部文件
8. 把 Dropzone 放到一个已存在的表单中