[網頁文件上傳簡化] Dropzone.js 完全攻略指南

Dropzone.js 完全攻略指南

目標
- 了解 Dropzone.js 是什麼、為什麼要使用
- 從安裝到基本使用、再到自訂化，逐步學習
- 搭配實際範例程式碼提供實戰技巧

1. Dropzone.js 是什麼？

Dropzone.js 是一個開源 JavaScript 函式庫，能輕鬆實作 HTML5 文件上傳。
- 拖放：只需用滑鼠拖曳檔案，即可立即開始上傳。
- 預覽：圖片檔案會自動顯示縮圖。
- 多檔案：一次可上傳多個檔案。
- 後端整合：透過 Ajax 將檔案送至伺服器，並接收回應。

為什麼選擇 Dropzone.js？
- 使用者體驗：直觀的 UI 讓上傳變得輕鬆。
- 開發便利：不必自行撰寫複雜的上傳邏輯。
- 可擴充性：藉由選項與事件，滿足大多數需求。

2. 安裝方式

2.1 使用 CDN

最簡單的方式是透過 CDN。將以下程式碼加入 index.html。

<link rel="stylesheet" href="https://unpkg.com/dropzone@5/dist/min/dropzone.min.css" />
<script src="https://unpkg.com/dropzone@5/dist/min/dropzone.min.js"></script>

Tip：最新版本可於 unpkg 查詢。

2.2 NPM / Yarn

若專案使用 npm，執行以下指令安裝。

npm install dropzone
# 或
yarn add dropzone

安裝後可透過 import 或 require 使用。

import Dropzone from 'dropzone';

注意：務必設定 Dropzone.autoDiscover = false;，以避免自動初始化。

3. 基本使用

3.1 HTML

<form action="/upload" class="dropzone" id="myDropzone"></form>

• action 指定檔案傳送的伺服器端點。
• class="dropzone" 讓 Dropzone 自動辨識。

3.2 JavaScript

Dropzone.autoDiscover = false; // 防止自動初始化

const myDropzone = new Dropzone('#myDropzone', {
  paramName: 'file',          // 伺服器接收檔案的參數名稱
  maxFilesize: 5,             // 最大檔案大小 (MB)
  acceptedFiles: 'image/*',   // 允許的檔案類型
  dictDefaultMessage: '將檔案拖曳至此或點擊上傳',
  init: function () {
    this.on('success', function (file, response) {
      console.log('上傳成功:', response);
    });
    this.on('error', function (file, errorMessage) {
      console.error('上傳失敗:', errorMessage);
    });
  }
});

核心選項
- url：檔案傳送的 URL（可替代 action）
- maxFiles：一次可上傳的檔案數量
- uploadMultiple：是否支援多檔案上傳
- autoProcessQueue：是否自動送檔（若為 false，需呼叫 processQueue()）

4. 自訂化

4.1 更改檔案預覽樣式

Dropzone 會自動為圖片檔案顯示縮圖。可用 CSS 調整樣式。

/* 調整縮圖尺寸 */
.dropzone .dz-image img {
  width: 100px;
  height: 100px;
  object-fit: cover;
}

/* 檔名字體 */
.dropzone .dz-details .dz-filename {
  font-weight: bold;
}

4.2 與伺服器通訊

伺服器需接收檔案並以 JSON 回傳。以下為 Node.js + Express 範例。

const express = require('express');
const multer  = require('multer');
const upload = multer({ dest: 'uploads/' });

const app = express();

app.post('/upload', upload.single('file'), (req, res) => {
  // 檔案資訊存於 req.file
  res.json({ success: true, filename: req.file.filename });
});

app.listen(3000, () => console.log('Server running on http://localhost:3000'));

Tip：upload.single('file') 的 'file' 必須與 Dropzone 的 paramName 相同。

4.3 刪除檔案功能

Dropzone 可設定刪除時發送 DELETE 請求。

const myDropzone = new Dropzone('#myDropzone', {
  // ...
  dictRemoveFile: '刪除',
  init: function () {
    this.on('removedfile', function (file) {
      // 送 DELETE 請求
      fetch('/delete', {
        method: 'DELETE',
        body: JSON.stringify({ filename: file.upload.filename }),
        headers: { 'Content-Type': 'application/json' }
      });
    });
  }
});

5. 實戰技巧

6. 結語

Dropzone.js 以簡單設定即可提供強大的檔案上傳 UI。
- 初始設定：CDN 或 npm 安裝 → autoDiscover = false → HTML 表單 + JS 實例
- 自訂化：利用選項、事件與 CSS，打造符合需求的介面與功能
- 伺服器整合：結合 multer 等中介軟體，輕鬆儲存檔案並回傳結果

接下來可深入探討 多檔案上傳 與 預覽自訂化，進一步提升使用者體驗。

參考資料
- 官方文件
- 範例程式碼庫

Happy coding! 🚀