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

CKTIS / JavaScript

Eventos HTML dragstart, dragover, drop e dragend

Distingue os eventos da origem e do destino para preparar os dados, aceitar a largada, ler o conteúdo e repor o estado mesmo que o arrastamento seja cancelado.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

source.draggable = true;
source.addEventListener("dragstart", onDragStart);
target.addEventListener("dragover", onDragOver);
target.addEventListener("drop", onDrop);
source.addEventListener("dragend", onDragEnd);

Estes eventos pertencem à API HTML de arrastar e largar do navegador, não ao ECMAScript. dragstart é disparado na origem, por exemplo, num elemento com draggable="true". No respetivo gestor síncrono, podes ler os dados do arrastamento e escrevê-los com event.dataTransfer.setData(type, text). A origem define as operações permitidas em effectAllowed. Chamar preventDefault() em dragstart impede o início do arrastamento.

dragover é disparado repetidamente sobre um possível destino. Se o destino aceitar o arrastamento, chama preventDefault() em dragover e, se necessário, define dropEffect como uma operação permitida pela origem. Em modo protegido, podes consultar os formatos através de dataTransfer.types, mas não ler os dados. O exemplo também cancela dragenter de acordo com o modelo da norma; nos navegadores mais comuns, cancelar dragover costuma bastar para uma zona como esta.

drop é disparado no destino quando os dados são largados num local que os aceita. Para tratar a largada de forma personalizada, chama preventDefault() para suprimir a ação predefinida e lê os dados de forma síncrona com getData(type). Um formato ausente dá uma cadeia de caracteres vazia. Trata o conteúdo largado como não fiável: usa textContent, e não innerHTML, para apresentar texto simples.

dragend é disparado na origem quando termina um arrastamento iniciado, mesmo que tenha sido cancelado ou que a largada tenha falhado. Repõe aqui o estado temporário; o evento por si só não comprova o sucesso. Se dropEffect for "none", não foi realizada nenhuma operação de largada. Se arrastares um ficheiro a partir do sistema operativo, a página não recebe os eventos da origem. O suporte varia consoante o navegador e o método de entrada; oferece uma forma de realizar a ação sem arrastar.

Exemplos

(() => {
  const panel = document.createElement("section");
  panel.style.cssText = "position:fixed;top:16px;left:16px;z-index:1000;padding:16px;background:white;color:black;display:flex;gap:16px";
  const source = document.createElement("div");
  const target = document.createElement("div");
  source.draggable = true;
  source.textContent = "Drag this card";
  source.style.cssText = "padding:16px;border:1px solid;cursor:grab";
  target.textContent = "Drop here";
  target.style.cssText = "padding:16px;border:2px dashed;min-width:100px";
  panel.append(source, target);
  document.body.append(panel);

  let active = false;
  const accepts = (event) => active && event.dataTransfer?.types.includes("text/plain");

  source.addEventListener("dragstart", (event) => {
    const transfer = event.dataTransfer;
    transfer.setData("text/plain", "Card");
    transfer.effectAllowed = "copy";
    active = true;
    source.style.opacity = "0.5";
    console.log("dragstart");
  });

  target.addEventListener("dragenter", (event) => {
    if (accepts(event)) event.preventDefault();
  });

  target.addEventListener("dragover", (event) => {
    if (!accepts(event)) return;
    event.preventDefault();
    event.dataTransfer.dropEffect = "copy";
  });

  target.addEventListener("drop", (event) => {
    if (!accepts(event)) return;
    event.preventDefault();
    const text = event.dataTransfer.getData("text/plain");
    target.textContent = text;
    console.log(`drop: ${text}`);
  });

  source.addEventListener("dragend", () => {
    active = false;
    source.style.opacity = "";
    console.log("dragend");
  });

  // Exercise the same handlers once without a pointer gesture.
  const transfer = new DataTransfer();
  const dispatch = (element, type) => element.dispatchEvent(new DragEvent(type, {
    bubbles: true,
    cancelable: type !== "dragend",
    dataTransfer: transfer,
  }));

  if (dispatch(source, "dragstart")) {
    dispatch(target, "dragenter");
    // dispatchEvent returns false when the handler cancels dragover.
    if (!dispatch(target, "dragover")) dispatch(target, "drop");
    dispatch(source, "dragend");
  }
})();

Resultado

dragstart
drop: Card
dragend

Executa o código na consola do navegador num separador em branco. O código aciona uma vez os gestores através de eventos sintéticos, sem precisares de arrastar nada, e o destino apresenta `Card`. Para experimentar o arrastamento nativo, arrasta «Drag this card» para o destino. Premir Esc durante outro arrastamento termina-o sem `drop`. Os eventos `dragover` repetidos não são registados.

Lições relacionadas

  • JavaScript · Lição 34 · Intermédio · Versão: 3

Fontes