Como Criar um Upload de Ficheiros com Dropzone.js
Criar uma interface moderna de upload de ficheiros não deveria exigir lutar com configurações complexas ou frameworks pesadas. Se precisar de funcionalidade de arrastar e soltar com feedback visual de progresso que funcione perfeitamente em todos os navegadores, Dropzone.js oferece uma solução leve, sem dependências, que leva minutos a implementar.
Este guia mostra-lhe como criar uma interface profissional de upload de ficheiros usando Dropzone.js, completa com capacidades de arrastar e soltar, barras de progresso e validação de ficheiros—tudo com JavaScript puro e sem complexidade de backend.
Pontos-Chave
- Dropzone.js fornece uploads de ficheiros por arrastar e soltar sem dependências
- Barras de progresso automáticas e pré-visualizações de ficheiros funcionam imediatamente
- Opções de configuração suportam restrições de tipo de ficheiro, limites de tamanho e validação personalizada
- Compatível com qualquer tecnologia de backend através de pedidos multipart/form-data padrão
Começar com Dropzone.js
Primeiro, inclua Dropzone.js a partir de uma CDN. Não são necessários gestores de pacotes ou ferramentas de build:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Dropzone File Upload</title>
<link rel="stylesheet" href="https://unpkg.com/dropzone@5.9.3/dist/min/dropzone.min.css">
</head>
<body>
<script src="https://unpkg.com/dropzone@5.9.3/dist/min/dropzone.min.js"></script>
</body>
</html>Criar o Seu Formulário de Upload
A abordagem mais simples usa um elemento de formulário com a classe dropzone. O Dropzone transforma-o automaticamente numa formulário de upload interativo:
<form action="/upload" class="dropzone" id="my-dropzone">
<div class="dz-message">
Drop files here or click to upload
</div>
</form>É tudo. Os utilizadores podem agora arrastar e soltar ficheiros ou clicar para navegar. O endpoint /upload recebe os ficheiros, quer esteja a usar PHP, Node.js, Python ou qualquer outra tecnologia de backend.
Configurar Tipos de Ficheiro e Limites de Tamanho
A maioria das aplicações precisa de restrições de upload. Configure o Dropzone para aceitar tipos de ficheiro específicos e impor limites de tamanho:
Dropzone.options.myDropzone = {
acceptedFiles: 'image/*,application/pdf,.doc,.docx',
maxFilesize: 5, // MB
maxFiles: 10,
addRemoveLinks: true,
dictDefaultMessage: 'Drop files here or click to upload (Max 5MB)'
};Esta configuração aceita imagens, PDFs e documentos Word até 5MB cada, com um máximo de 10 ficheiros por sessão.
Discover how at OpenReplay.com.
Adicionar Feedback de Barra de Progresso
Barras de progresso aparecem automaticamente durante os uploads, mas pode personalizar o seu comportamento usando event listeners:
Dropzone.options.myDropzone = {
init: function() {
this.on("uploadprogress", function(file, progress) {
console.log("File progress", progress);
});
this.on("success", function(file, response) {
console.log("Upload successful!");
});
this.on("error", function(file, errorMessage) {
console.log("Upload failed:", errorMessage);
});
}
};Personalização Avançada do Frontend
Para mais controlo sobre a experiência de upload, crie uma dropzone personalizada programaticamente:
// Disable auto-discovery for all forms
Dropzone.autoDiscover = false;
// Create custom dropzone
const myDropzone = new Dropzone("#upload-area", {
url: "/upload",
thumbnailWidth: 120,
thumbnailHeight: 120,
parallelUploads: 2,
previewTemplate: document.getElementById('preview-template').innerHTML,
autoQueue: false,
previewsContainer: "#previews",
clickable: ".fileinput-button"
});
// Manual upload trigger
document.getElementById("submit-all").addEventListener("click", function() {
myDropzone.enqueueFiles(myDropzone.getFilesWithStatus(Dropzone.ADDED));
});Validação de Ficheiros e Feedback ao Utilizador
Implemente validação do lado do cliente para feedback imediato ao utilizador:
Dropzone.options.myDropzone = {
accept: function(file, done) {
if (file.size === 0) {
done("Empty files are not allowed");
} else if (file.name.length > 100) {
done("Filename too long");
} else {
done(); // Accept file
}
},
init: function() {
this.on("addedfile", function(file) {
// File added to queue
if (this.files.length > this.options.maxFiles) {
this.removeFile(file);
alert("Maximum files exceeded");
}
});
}
};Integração com Qualquer Backend
Dropzone.js envia ficheiros como pedidos POST multipart/form-data padrão, tornando-o compatível com qualquer tecnologia de servidor. O nome do parâmetro padrão é file, mas pode personalizá-lo:
Dropzone.options.myDropzone = {
paramName: "upload", // Changes field name from 'file' to 'upload'
headers: {
"X-CSRF-Token": document.querySelector('meta[name="csrf-token"]').content
}
};Quer o seu backend execute PHP, Node.js, Django ou Rails, recebe pedidos de upload de ficheiros padrão que o código de servidor existente pode processar sem modificação.
Conclusão
Dropzone.js transforma inputs básicos de ficheiros em interfaces de upload profissionais com código mínimo. A sua funcionalidade de arrastar e soltar, barras de progresso automáticas e extensas opções de personalização tornam-no ideal para aplicações frontend modernas que priorizam a experiência do utilizador sem adicionar dependências de frameworks.
O tamanho de 13KB comprimido da biblioteca e zero dependências significam que pode adicionar capacidades sofisticadas de upload de ficheiros sem inchar o seu bundle JavaScript ou complicar o seu processo de build.
Perguntas Frequentes
Sim, o Dropzone.js suporta múltiplos uploads de ficheiros por padrão. Pode controlar uploads paralelos com a opção parallelUploads e definir limites máximos de ficheiros usando maxFiles. Os ficheiros podem ser carregados individualmente ou em lotes dependendo da sua configuração.
Erros do servidor são tratados através do event listener error. Retorne códigos de status HTTP como 400 ou 500 do seu servidor com mensagens de erro no corpo da resposta. O Dropzone exibirá automaticamente estes erros e marcará o upload do ficheiro como falhado.
Sim, pode fazer upload diretamente para S3 gerando URLs pré-assinados no lado do servidor e configurando o Dropzone para usá-los. Defina a opção url dinamicamente para cada ficheiro e inclua os cabeçalhos necessários como tokens de autenticação na opção de configuração headers.
O Dropzone gera automaticamente miniaturas para ficheiros de imagem. Para outros tipos de ficheiro, pode personalizar o template de pré-visualização usando a opção previewTemplate. A configuração autoQueue false permite aos utilizadores rever ficheiros antes de acionar manualmente os uploads.
Understand every bug
Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.
