Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

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.

Fontes