Objeto dataTransfer

O objeto dataTransfer é associado a todo evento de arrastamento e é o único canal de comunicação entre a origem e o destino. Ele transporta dados da carga útil, listas de arquivos, efeitos permitidos e o efeito de soltura escolhido.

A origem grava cargas úteis tipadas com e.dataTransfer.setData(format, value). O destino as lê com e.dataTransfer.getData(format). Ambos os argumentos são cadeias de caracteres; os valores são convertidos em cadeias de caracteres antes do armazenamento.

Armazenar a mesma carga útil em vários tipos torna o arrastamento interoperável: "text/plain" funciona em qualquer editor de texto, "text/uri-list" é reconhecido pelos navegadores como uma URL e "text/html" preserva a formatação em processadores de texto. O destino escolhe o tipo que entende.

Por privacidade, o navegador expõe apenas a lista de tipos — não os valores — aos manipuladores de entrada e arrastamento sobre o destino por meio de e.dataTransfer.types. Os dados reais só podem ser lidos dentro do evento de soltura de um destino que a aceite.

Quando o usuário arrasta a partir da área de trabalho, e.dataTransfer.files é um FileList de objetos de arquivo. Ela fica vazia para arrastamentos originados dentro da página. Trate-a como a forma oficial de detectar uma soltura externa de arquivos e acessar tamanho, nome e tipo.

e.dataTransfer.items expõe tanto cadeias de caracteres quanto arquivos como objetos DataTransferItem. Cada item tem kind ("string" ou "file"), type (MIME) e getAsString(cb) / getAsFile(). items é a alternativa moderna e ciente dos tipos para files + getData.

effectAllowed é definido pela origem no início do arrastamento e lista as operações compatíveis com a origem. dropEffect é definido pelo destino durante o arrastamento sobre o destino e escolhe uma dessas operações. O navegador cancela a soltura se os dois valores forem incompatíveis.

e.dataTransfer.setDragImage(node, x, y) substitui a imagem fantasma padrão. Passe um elemento DOM fora da tela, estilizado conforme desejar, além do deslocamento do cursor em relação a esse elemento. A alteração se aplica apenas ao arrastamento atual.

e.dataTransfer.clearData() apaga todos os formatos; clearData("text/plain") remove um único formato. Raramente é necessário, pois dataTransfer é criado novamente a cada arrastamento, mas é útil quando você começa a preencher dados e depois decide cancelar.

Arquivos arrastados de uma página na origem A para uma página na origem B ainda são entregues — a API funciona entre origens. No entanto, a página receptora vê apenas o que a origem colocou explicitamente em dataTransfer; não é concedido acesso arbitrário ao DOM.

Ao gravar o tipo "DownloadURL" (setData("DownloadURL", "image/png:filename.png:https://...")), uma página pode permitir que o usuário arraste um arquivo para fora do navegador, até a área de trabalho. O suporte é limitado (navegadores baseados em Chromium), portanto detecte a situação e ofereça uma alternativa adequada.

Por que dataTransfer.getData() não pode retornar o valor realmente armazenado durante o evento de arrasto sobre o alvo?

dataTransfer é a ponte entre a origem do arrasto e o alvo da soltura. Utilize setData/getData para cargas úteis de cadeias de caracteres tipadas, itens para uma visão unificada de arquivos e cadeias de caracteres, arquivos para solturas do computador, setDragImage para pré-visualizações personalizadas e effectAllowed/dropEffect para negociar a operação.