CKTIS / JavaScript
Eventos do ciclo de arrastamento HTML
Conheça os sete eventos de arrastamento HTML, a sua distribuição entre a origem e o destino e quando é possível ler ou alterar DataTransfer. Perceba por que razão dragover precisa de preventDefault() e por que dragend não prova que a largada foi bem-sucedida.
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
source.addEventListener("dragstart", handler);
source.addEventListener("drag", handler);
source.addEventListener("dragend", handler);
target.addEventListener("dragenter", handler);
target.addEventListener("dragover", handler);
target.addEventListener("dragleave", handler);
target.addEventListener("drop", handler);Os eventos do ciclo de arrastamento HTML são sete eventos da API HTML Drag and Drop do navegador, não uma funcionalidade de uma edição específica do ECMAScript. A origem recebe dragstart quando o arrastamento começa, eventos drag repetidos durante o arrastamento e dragend quando termina. Os potenciais destinos recebem dragenter à entrada, eventos dragover repetidos, dragleave à saída e drop quando um elemento é largado num destino válido. O número e o intervalo das repetições não são fixos.
Torne um elemento normal arrastável com draggable = true. Em dragstart, escreva texto com event.dataTransfer.setData(). Os dados só podem ser alterados em dragstart, e o seu conteúdo pode ser lido em dragstart e drop; em dragover, verifique os tipos disponíveis em vez do conteúdo. Na prática, nos navegadores basta chamar preventDefault() em dragover quando um destino personalizado aceita os dados arrastados. No entanto, a norma HTML exige que se cancele também dragenter para que um elemento normal seja selecionado como destino personalizado de largada. Em drop, cancele também o comportamento predefinido e leia os dados com getData().
Use dragend para a limpeza, mesmo que o gesto seja cancelado, por exemplo com Escape; a sua ocorrência não prova que tenha sido bem-sucedido. effectAllowed define as operações permitidas pela origem, enquanto dropEffect indica a operação selecionada; nenhum dos dois move automaticamente elementos DOM. Trate os dados externos como não fiáveis: valide os valores e apresente o texto com textContent.
O exemplo copia apenas token-1 e disponibiliza um botão como alternativa ao arrastamento. Teste um gesto real no navegador de destino: um DragEvent sintético não reproduz toda a operação gerida pelo navegador. Arrastar um ficheiro a partir do sistema operativo não dispara na página os eventos dragstart ou dragend do lado da origem. A disponibilidade do Node 24 não comprova o suporte destas interfaces do navegador.
Exemplos
const panel = document.createElement("section");
const source = document.createElement("p");
const target = document.createElement("p");
const alternative = document.createElement("button");
const output = document.createElement("p");
source.textContent = "Drag token-1";
source.draggable = true;
target.textContent = "Drop here";
target.style.cssText = "padding: 2rem; border: 2px dashed;";
alternative.type = "button";
alternative.textContent = "Copy token-1 without dragging";
output.setAttribute("role", "status");
output.textContent = "Ready";
panel.append(source, target, alternative, output);
document.body.append(panel);
function accept(value) {
if (value === "token-1") {
output.textContent = `Dropped: ${value}`;
}
}
source.addEventListener("dragstart", (event) => {
event.dataTransfer.setData("text/plain", "token-1");
event.dataTransfer.effectAllowed = "copy";
source.style.opacity = "0.5";
});
target.addEventListener("dragover", (event) => {
if (event.dataTransfer.types.includes("text/plain")) {
event.preventDefault();
event.dataTransfer.dropEffect = "copy";
}
});
target.addEventListener("drop", (event) => {
event.preventDefault();
accept(event.dataTransfer.getData("text/plain"));
});
source.addEventListener("dragend", () => {
source.style.opacity = "";
});
alternative.addEventListener("click", () => accept("token-1"));Resultado
Dropped: token-1
O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.