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

CKTIS / JavaScript

DataTransfer: operações permitidas, efeito ao largar e dados

A origem define as operações permitidas, o destino escolhe uma e `setData()` guarda o texto que o destino pode ler ao largar.

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

Sintaxe

// Source: write to this dragstart event's data store.
source.addEventListener("dragstart", (event) => {
  const transfer = event.dataTransfer;
  transfer.effectAllowed = "copyMove";
  transfer.setData("text/plain", "card-34");
});

// Target: accept a compatible drag using this dragover event.
target.addEventListener("dragover", (event) => {
  const transfer = event.dataTransfer;
  if (!transfer.types.includes("text/plain")) return;
  event.preventDefault();
  transfer.dropEffect = "copy";
});

// Target: read from this drop event's data store.
target.addEventListener("drop", (event) => {
  event.preventDefault();
  const text = event.dataTransfer.getData("text/plain");
});

event.dataTransfer dá acesso ao objeto DataTransfer de um evento de arrastar e largar. Esta API da plataforma Web é definida na norma HTML e não faz parte do ECMAScript 2024. Confirma se é suportada no ambiente de execução de destino.

Origem: define effectAllowed de forma síncrona em dragstart. copy, move e link permitem, respetivamente, copiar, mover ou criar uma ligação. copyLink, copyMove e linkMove permitem uma das duas operações indicadas, all permite as três e none não permite nenhuma. O valor inicial uninitialized também permite as três, mas pode influenciar a escolha predefinida. Os valores inválidos e as escritas fora do modo de leitura e escrita são ignorados.

Destino: em dragover, se aceitares o arrastamento, chama preventDefault() e atribui a dropEffect um valor permitido entre copy, move e link. none significa que não há operação; os restantes valores são ignorados. O navegador inicializa esta propriedade em dragenter e dragover de acordo com as operações permitidas e as convenções da plataforma, incluindo as teclas modificadoras. Uma escolha incompatível não permite largar. Num drop aceite, chama preventDefault() e executa a operação no teu código: definir move não move um elemento do DOM.

Dados: setData(format, data) recebe duas cadeias de caracteres e devolve undefined. Adiciona texto para um formato ou substitui o texto já associado a esse formato. As letras ASCII do formato passam a minúsculas; text e url são nomes alternativos de text/plain e text/uri-list. Se o armazenamento não permitir escrita, o método não altera nada.

Escreve o texto de forma síncrona em dragstart. No destino, lê-o de forma síncrona com getData() em drop, quando o armazenamento é só de leitura. Durante dragover, podes consultar types, mas não ler o conteúdo. Guarda a cadeia lida para a usares mais tarde, não o objeto do evento. Trata os dados largados como não fidedignos e apresenta texto simples com textContent.

Exemplos

(() => {
  const source = document.createElement("p");
  source.textContent = "Drag card-34";
  source.draggable = true;
  source.style.cursor = "grab";

  const target = document.createElement("div");
  const prompt = "Drop here";
  target.textContent = prompt;
  target.style.cssText = "border: 2px dashed; padding: 24px;";

  const format = "text/plain";
  source.addEventListener("dragstart", (event) => {
    event.dataTransfer.effectAllowed = "copy";
    event.dataTransfer.setData(format, "card-34");
  });

  function acceptCopy(event) {
    if (!event.dataTransfer.types.includes(format)) return;
    event.preventDefault();
    event.dataTransfer.dropEffect = "copy";
  }
  target.addEventListener("dragenter", acceptCopy);
  target.addEventListener("dragover", acceptCopy);

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

  document.body.append(source, target);

  // Exercise the handlers once without mouse input. These synthetic events
  // share an explicitly created store; they do not start a native drag.
  const transfer = new DataTransfer();
  function dispatchDrag(element, type) {
    return element.dispatchEvent(new DragEvent(type, {
      bubbles: true,
      cancelable: true,
      dataTransfer: transfer,
    }));
  }

  if (!dispatchDrag(source, "dragstart")) return;
  dispatchDrag(target, "dragenter");
  const accepted = !dispatchDrag(target, "dragover");
  if (accepted && transfer.effectAllowed === "copy" && transfer.dropEffect === "copy") {
    dispatchDrag(target, "drop");
    target.textContent = prompt; // Reset the box for a native drag.
  }
})();

Resultado

copy: card-34

Executa o exemplo na consola do navegador numa página em branco. Uma simulação da operação de largar mostra `copy: card-34` na consola e repõe o texto «Drop here». Depois, arrasta «Drag card-34» com o rato para essa caixa. A caixa apresenta `card-34`, a origem fica no mesmo sítio e a consola volta a mostrar `copy: card-34`.

Lições relacionadas

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

Fontes