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