Lição 36 de 50

HTML5 Drag and Drop API: Guia Prático | Web Academy

A HTML5 Drag and Drop API é a especificação nativa que permite aos desenvolvedores construir interfaces ricas e interativas onde o usuário pode clicar em elementos, arrastá-los pela tela com o cursor e soltá-los em recipientes designados — ou até mesmo arrastar arquivos diretamente da área de trabalho do computador para dentro do navegador. Essa API eliminou a dependência histórica de bibliotecas pesadas de JavaScript para gerenciar coordenadas e eventos manuais de mouse.

📑 Índice do Conteúdo

1. Como Funciona a Mecânica Nativa de Arrastar e Soltar

Por padrão nos navegadores, apenas dois elementos podem ser arrastados nativamente: links (<a href="...">) e imagens (<img>). Para que qualquer outro elemento HTML comum (como um <div>, <li> ou <article>) se torne arrastável, é obrigatório declarar o atributo booleano:

HTML5 4 linhas

<!-- Ativando o comportamento arrastável -->
<div class="cartao-tarefa" draggable="true">
    Refatorar Folha de Estilos
</div>

<!-- Ativando o comportamento arrastável -->
<div class="cartao-tarefa" draggable="true">
Refatorar Folha de Estilos
</div>

2. O Ciclo de Vida dos Eventos de Drag & Drop

O fluxo de arrastar e soltar é governado por eventos disparados em dois atores diferentes: o elemento de origem (o item que se move) e a zona de destino (o container que recebe o item):

Ator	Evento	Quando é Disparado?
Origem (Item arrastado)	`dragstart`	No exato instante em que o usuário inicia o arrasto do elemento.
	`drag`	Disparado continuamente enquanto o elemento está sendo movido pelo cursor.
	`dragend`	Quando o usuário solta o botão do mouse, finalizando o arrasto (com sucesso ou cancelado).
Destino (Zona de Drop)	`dragenter`	Quando o item arrastado cruza a borda e entra no espaço visual da zona de soltura.
	`dragover`	Disparado a cada milissegundo enquanto o item paira sobre a zona. Obrigatório chamar `e.preventDefault()` para autorizar a soltura!
	`dragleave`	Quando o cursor com o item sai da área da zona sem ter sido solto.
	`drop`	Quando o botão do mouse é liberado sobre a zona de soltura válida.

💡 A Regra de Ouro do Evento dragover

Por segurança e padrão da especificação web, o navegador proíbe que dados sejam soltos em qualquer elemento comum da página. Se você não interceptar o evento dragover chamando event.preventDefault(), o evento drop nunca será disparado!

3. O Objeto DataTransfer: A Maleta de Dados do Cursor

Durante o ciclo de arrasto, os dados são transportados de um lado para o outro através da propriedade event.dataTransfer. Seus métodos fundamentais são:

e.dataTransfer.setData(tipoMime, valor): Grava uma informação no buffer (ex: o ID do elemento no formato 'text/plain').
e.dataTransfer.getData(tipoMime): Lê a informação gravada no momento em que o item é solto na zona.
e.dataTransfer.effectAllowed: Define os efeitos permitidos (ex: 'move', 'copy' ou 'link').

4. Código Prático Completo: Painel Kanban Interativo

Abaixo construímos um mini-quadro de produtividade com duas colunas onde você pode transferir cartões de tarefas livremente entre os estados:

HTML5 14 linhas

<div class="kanban-board">
    <!-- Coluna 1: A Fazer -->
    <div class="kanban-column" id="coluna-pendente">
        <h3>📋 A Fazer</h3>
        <div class="kanban-item" id="item-1" draggable="true">Configurar Meta Tags SEO</div>
        <div class="kanban-item" id="item-2" draggable="true">Criar Paleta de Cores HSL</div>
    </div>
 
    <!-- Coluna 2: Concluído -->
    <div class="kanban-column" id="coluna-concluido">
        <h3>✅ Concluído</h3>
        <div class="kanban-item" id="item-3" draggable="true">Estruturar Layout Semântico</div>
    </div>
</div>

<div class="kanban-board">
<!-- Coluna 1: A Fazer -->
<div class="kanban-column" id="coluna-pendente">
<h3>📋 A Fazer</h3>
<div class="kanban-item" id="item-1" draggable="true">Configurar Meta Tags SEO</div>
<div class="kanban-item" id="item-2" draggable="true">Criar Paleta de Cores HSL</div>
</div>
<!-- Coluna 2: Concluído -->
<div class="kanban-column" id="coluna-concluido">
<h3>✅ Concluído</h3>
<div class="kanban-item" id="item-3" draggable="true">Estruturar Layout Semântico</div>
</div>
</div>

CSS3 42 linhas

/* Estilos do Quadro Kanban */
.kanban-board {
    display: flex;
    gap: 20px;
    margin: 20px 0;
}
 
.kanban-column {
    flex: 1;
    min-height: 250px;
    padding: 16px;
    background-color: #0f172a;
    border: 2px dashed #334155;
    border-radius: 8px;
    transition: all 0.2s ease;
}
 
/* Efeito visual quando um item está sobre a coluna */
.kanban-column.drag-over {
    background-color: #1e293b;
    border-color: #38bdf8;
}
 
.kanban-item {
    padding: 12px 16px;
    margin-bottom: 10px;
    background-color: #1e293b;
    color: #f8fafc;
    border: 1px solid #475569;
    border-radius: 6px;
    cursor: grab;
    transition: opacity 0.2s;
}
 
.kanban-item:active {
    cursor: grabbing;
}
 
/* Item fica translúcido enquanto está sendo arrastado */
.kanban-item.is-dragging {
    opacity: 0.4;
}

/* Estilos do Quadro Kanban */
.kanban-board {
display: flex;
gap: 20px;
margin: 20px 0;
}
.kanban-column {
flex: 1;
min-height: 250px;
padding: 16px;
background-color: #0f172a;
border: 2px dashed #334155;
border-radius: 8px;
transition: all 0.2s ease;
}
/* Efeito visual quando um item está sobre a coluna */
.kanban-column.drag-over {
background-color: #1e293b;
border-color: #38bdf8;
}
.kanban-item {
padding: 12px 16px;
margin-bottom: 10px;
background-color: #1e293b;
color: #f8fafc;
border: 1px solid #475569;
border-radius: 6px;
cursor: grab;
transition: opacity 0.2s;
}
.kanban-item:active {
cursor: grabbing;
}
/* Item fica translúcido enquanto está sendo arrastado */
.kanban-item.is-dragging {
opacity: 0.4;
}

JavaScript 42 linhas

// JavaScript: Gerenciamento dos Eventos
const itens = document.querySelectorAll('.kanban-item');
const colunas = document.querySelectorAll('.kanban-column');
 
// 1. Configura os itens que podem ser arrastados
itens.forEach(item => {
    item.addEventListener('dragstart', (e) => {
        item.classList.add('is-dragging');
        // Grava o ID do elemento no dataTransfer
        e.dataTransfer.setData('text/plain', item.id);
        e.dataTransfer.effectAllowed = 'move';
    });
 
    item.addEventListener('dragend', () => {
        item.classList.remove('is-dragging');
    });
});
 
// 2. Configura as zonas de soltura (colunas)
colunas.forEach(coluna => {
    coluna.addEventListener('dragover', (e) => {
        e.preventDefault(); // OBRIGATÓRIO: autoriza o drop!
        e.dataTransfer.dropEffect = 'move';
        coluna.classList.add('drag-over');
    });
 
    coluna.addEventListener('dragleave', () => {
        coluna.classList.remove('drag-over');
    });
 
    coluna.addEventListener('drop', (e) => {
        e.preventDefault();
        coluna.classList.remove('drag-over');
        
        // Recupera o ID do elemento arrastado e anexa à nova coluna
        const idItem = e.dataTransfer.getData('text/plain');
        const elementoArrastado = document.getElementById(idItem);
        if (elementoArrastado) {
            coluna.appendChild(elementoArrastado);
        }
    });
});

// JavaScript: Gerenciamento dos Eventos
const itens = document.querySelectorAll('.kanban-item');
const colunas = document.querySelectorAll('.kanban-column');
// 1. Configura os itens que podem ser arrastados
itens.forEach(item => {
item.addEventListener('dragstart', (e) => {
item.classList.add('is-dragging');
// Grava o ID do elemento no dataTransfer
e.dataTransfer.setData('text/plain', item.id);
e.dataTransfer.effectAllowed = 'move';
});
item.addEventListener('dragend', () => {
item.classList.remove('is-dragging');
});
});
// 2. Configura as zonas de soltura (colunas)
colunas.forEach(coluna => {
coluna.addEventListener('dragover', (e) => {
e.preventDefault(); // OBRIGATÓRIO: autoriza o drop!
e.dataTransfer.dropEffect = 'move';
coluna.classList.add('drag-over');
});
coluna.addEventListener('dragleave', () => {
coluna.classList.remove('drag-over');
});
coluna.addEventListener('drop', (e) => {
e.preventDefault();
coluna.classList.remove('drag-over');
// Recupera o ID do elemento arrastado e anexa à nova coluna
const idItem = e.dataTransfer.getData('text/plain');
const elementoArrastado = document.getElementById(idItem);
if (elementoArrastado) {
coluna.appendChild(elementoArrastado);
}
});
});

🧪 Quer testar o Kanban com Drag and Drop agora?
⚡ Abrir no Playground IDE →

5. Arrastando Arquivos do Sistema Operacional para o Navegador

A mesma API é capaz de interceptar arquivos arrastados da pasta do usuário (Windows Explorer ou Mac Finder). No evento drop, você acessa a lista de arquivos via e.dataTransfer.files:

JavaScript 10 linhas

const dropZone = document.querySelector('#areaUpload');
 
dropZone.addEventListener('drop', (e) => {
    e.preventDefault();
    const arquivos = e.dataTransfer.files; // Coleção FileList
    if (arquivos.length > 0) {
        console.log(`Arquivo recebido: ${arquivos[0].name} (${arquivos[0].size} bytes)`);
        // Aqui você pode enviar via FormData ou ler com FileReader!
    }
});

const dropZone = document.querySelector('#areaUpload');
dropZone.addEventListener('drop', (e) => {
e.preventDefault();
const arquivos = e.dataTransfer.files; // Coleção FileList
if (arquivos.length > 0) {
console.log(`Arquivo recebido: ${arquivos[0].name} (${arquivos[0].size} bytes)`);
// Aqui você pode enviar via FormData ou ler com FileReader!
}
});

6. Ferramentas Relacionadas & Próximos Passos

Explore as ferramentas do portal para manipular arquivos e gráficos com máxima produtividade:

Hub Master de Imagens: Ferramentas completas para processamento em lote de imagens via drag-and-drop.
Hub Master de PDFs: Ferramentas para mesclar, dividir e comprimir documentos PDF no navegador.
Central do Desenvolvedor Web: Testadores de código, manipuladores de eventos e conversores.
Lição 35: SVG Inline no HTML5: Gráficos vetoriais de alta resolução para ícones arrastáveis.
Lição 37: API de Geolocalização: Descubra como obter as coordenadas geográficas do usuário no HTML5.