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

CKTIS / JavaScript

DragEvent.dataTransfer — dados de arrastamento

DragEvent.dataTransfer expõe o objeto DataTransfer de um evento de arrastamento. O acesso aos respetivos dados depende da fase da operação; um evento criado por um script pode devolver null.

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 // DataTransfer | null

DragEvent.dataTransfer é uma propriedade só de leitura que devolve DataTransfer ou null. O navegador associa um objeto aos eventos de arrastamento nativos. Em new DragEvent("drop"), dataTransfer é null por predefinição; o construtor aceita um objeto explícito. A referência é só de leitura, não todo o conteúdo do objeto.

Numa operação de arrastamento nativa, é possível escrever dados com setData() durante dragstart. Durante drop, é possível lê-los com getData(), mas não alterá-los. Nos restantes eventos da operação, o armazenamento de dados está em modo protegido: é possível verificar os formatos através de types, mas getData() devolve uma cadeia vazia. files expõe os ficheiros e items os itens de dados.

Criar um evento dragover através de um script e passar-lhe um novo objeto DataTransfer não coloca o armazenamento em modo protegido. getData() continua a poder devolver os dados escritos com setData().

Para que um elemento normal aceite uma ação de largar, cancela dragover com preventDefault(). Numa operação de arrastamento nativa, lê os dados de forma síncrona no manipulador de drop, antes de terminar o acesso ao armazenamento. Copia os valores necessários antes de realizar trabalho assíncrono.

Esta é uma API de navegador definida por HTML, não uma funcionalidade de uma edição específica de ECMAScript. A disponibilidade no Node 24 não comprova o suporte nos navegadores. O exemplo requer os construtores DragEvent e DataTransfer; criar um evento através de um script não inicia um arrastamento nativo.

Exemplos

(() => {
  const transfer = new DataTransfer();
  transfer.setData("text/plain", "CKTIS");

  const event = new DragEvent("drop", { dataTransfer: transfer });
  const emptyEvent = new DragEvent("drop");

  console.log(event.dataTransfer === transfer);
  console.log(event.dataTransfer.getData("text/plain"));
  console.log(emptyEvent.dataTransfer === null);
})();

Resultado

true
CKTIS
true

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