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

CKTIS / JavaScript

DataTransfer: dados e operações permitidas ao arrastar

DataTransfer transporta dados durante o arrastamento. Saiba como effectAllowed limita as operações na origem, setData() guarda os dados e dropEffect seleciona a operação no destino, sem realizar por si só a cópia ou a deslocação.

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

event.dataTransfer.setData(format, data);
event.dataTransfer.effectAllowed = "copyMove";
event.dataTransfer.dropEffect = "copy";

DataTransfer é uma interface da Web API, não faz parte do ECMAScript. Durante um arrastamento, está disponível como event.dataTransfer. Também é usada por outras interfaces, como as da área de transferência, mas as propriedades das operações de arrastamento não têm aí o mesmo papel. Ter o Node 24 não comprova o suporte desta API por um navegador; o exemplo requer um navegador que suporte o arrastamento e a largada nativos de HTML.

DataTransfer.setData(format, data) guarda texto sob um tipo especificado, como text/plain, e devolve undefined. Segundo a norma HTML, ao voltar a escrever dados do mesmo tipo, o item anterior é removido e o novo é acrescentado ao fim da lista, o que pode alterar a ordem dos tipos. Num arrastamento real, escreve os dados em dragstart e lê-os com getData() em drop.

DataTransfer.effectAllowed especifica as operações permitidas pela origem e deve ser definido em dragstart. Os valores são none, copy, copyLink, copyMove, link, linkMove, move, all e o valor predefinido uninitialized, que permite todas as operações. O destino escolhe uma operação compatível através de DataTransfer.dropEffect: none, copy, link ou move. Os valores inválidos de qualquer uma das propriedades são ignorados.

Em dragover, chama preventDefault() para permitir a largada e define dropEffect em cada evento. Esta propriedade influencia a indicação visual, normalmente o cursor, mas não copia nem elimina dados por si só. A aplicação implementa esse comportamento: o exemplo lê o texto em drop e apresenta-o através de textContent, sem o interpretar como HTML. Um efeito move também exigiria tratar a remoção dos dados da origem.

Exemplos

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>DataTransfer copy</title>
<p id="source" draggable="true">Drag this text</p>
<div id="target" style="border: 2px dashed; padding: 2rem">Drop here</div>
<pre id="output" aria-live="polite"></pre>
<script>
  const source = document.getElementById("source");
  const target = document.getElementById("target");
  const output = document.getElementById("output");
  let localDrag = false;

  source.addEventListener("dragstart", (event) => {
    localDrag = true;
    event.dataTransfer.setData("text/plain", "CKTIS");
    event.dataTransfer.effectAllowed = "copy";
  });

  source.addEventListener("dragend", () => {
    localDrag = false;
  });

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

  target.addEventListener("drop", (event) => {
    if (!localDrag) return;
    event.preventDefault();
    const text = event.dataTransfer.getData("text/plain");
    target.textContent = text;
    output.textContent = `Copied: ${text}`;
  });
</script>
</html>

Resultado

Copied: CKTIS

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