DragEvent.dataTransfer — Eigenschaft · JavaScript-Referenz

Signatur

DragEvent.dataTransfer

Beschreibung

Die schreibgeschützte Eigenschaft dataTransfer eines DragEvent verweist auf ein DataTransfer-Objekt. Darüber tauschen Quelle und Ziel einer Drag-and-Drop-Operation Daten aus: Beim dragstart legt man mit setData() Daten ab, beim drop liest man sie mit getData() oder über files bzw. items wieder aus.

Außerdem steuert man über das Objekt die visuelle Rückmeldung: effectAllowed (in der Quelle) legt fest, welche Operationen erlaubt sind (copy, move, link …), dropEffect (im Ziel) legt fest, welcher Mauszeiger angezeigt wird. Mit setDragImage() lässt sich ein eigenes Vorschaubild setzen.

Die Eigenschaft selbst ist schreibgeschützt: Man kann ihr kein anderes Objekt zuweisen, wohl aber das enthaltene DataTransfer-Objekt über seine Methoden verändern. Der Zugriff auf die Daten wird vom Browser je nach Ereignisphase eingeschränkt (Drag Data Store Mode).

Typische Einsatzfälle sind sortierbare Listen, Kanban-Boards, das Verschieben von Elementen zwischen Containern sowie Datei-Uploads per Drag and Drop aus dem Betriebssystem.

Rückgabewert

Typ

DataTransfer | null

Beschreibung

Das DataTransfer-Objekt der Ziehoperation. Bei Browser-ausgelösten Drag-Ereignissen ist es immer vorhanden; bei einem per new DragEvent() ohne dataTransfer-Option erzeugten Ereignis ist der Wert null.

Beispiele

Daten beim Ziehen setzen und beim Ablegen lesen

// HTML: <li id="task-1" draggable="true">Aufgabe 1</li> und <ul id="done"></ul>
const item = document.getElementById('task-1');
const ziel = document.getElementById('done');

item.addEventListener('dragstart', (event) => {
  event.dataTransfer.setData('text/plain', event.target.id);
  event.dataTransfer.effectAllowed = 'move';
});

// dragover muss abgebrochen werden, sonst ist kein Drop möglich
ziel.addEventListener('dragover', (event) => {
  event.preventDefault();
  event.dataTransfer.dropEffect = 'move';
});

ziel.addEventListener('drop', (event) => {
  event.preventDefault();
  const id = event.dataTransfer.getData('text/plain');
  ziel.appendChild(document.getElementById(id));
  console.log(`Verschoben: ${id}`);
});

Verschoben: task-1

Dateien per Drag and Drop entgegennehmen

const dropZone = document.querySelector('#upload');

dropZone.addEventListener('dragover', (event) => {
  // Nur reagieren, wenn tatsächlich Dateien gezogen werden
  if (event.dataTransfer.types.includes('Files')) {
    event.preventDefault();
    event.dataTransfer.dropEffect = 'copy';
  }
});

dropZone.addEventListener('drop', async (event) => {
  event.preventDefault();
  for (const file of event.dataTransfer.files) {
    const text = file.type.startsWith('text/') ? await file.text() : '';
    console.log(file.name, file.size, text.slice(0, 20));
  }
});

notizen.txt 1234 Einkaufsliste: Milc

Eigenes Vorschaubild und mehrere Formate

const karte = document.querySelector('.karte');
const vorschau = new Image();
vorschau.src = '/img/drag-icon.png';

karte.addEventListener('dragstart', (event) => {
  const dt = event.dataTransfer;
  const daten = { id: karte.dataset.id, titel: karte.textContent.trim() };
  dt.setData('application/json', JSON.stringify(daten));
  dt.setData('text/plain', daten.titel); // Fallback für andere Ziele
  dt.setDragImage(vorschau, 16, 16);
  console.log(dt.types);
});

["application/json", "text/plain"]

Synthetisches DragEvent (z. B. in Tests)

const dt = new DataTransfer();
dt.setData('text/plain', 'Hallo');

const event = new DragEvent('drop', { dataTransfer: dt, bubbles: true });
console.log(event.dataTransfer.getData('text/plain'));

const ohne = new DragEvent('drop');
console.log(ohne.dataTransfer);

Hallo null

// Wichtig · Fallstricke

Geschützter Modus: In dragenter, dragover und dragleave liefert getData() aus Sicherheitsgründen einen leeren String. Nur types ist lesbar. Die eigentlichen Daten stehen erst im drop zur Verfügung; schreiben (setData()) geht nur im dragstart.
Drop aktivieren: Ohne event.preventDefault() in dragover (und idealerweise dragenter) wird drop nie ausgelöst. Im drop-Handler ebenfalls preventDefault() aufrufen, sonst öffnet der Browser z. B. abgelegte Dateien oder Links.
Nicht asynchron zugreifen: Das DataTransfer-Objekt ist nur während der synchronen Ereignisbehandlung gültig. Nach einem await sind items leer; Dateien daher zuerst in ein Array kopieren ([...event.dataTransfer.files]).
Sicherheit: Abgelegte Daten stammen potenziell aus fremden Quellen (andere Tabs, Anwendungen). text/html-Inhalte nie ungeprüft per innerHTML einfügen – XSS-Gefahr. Lieber textContent verwenden oder sanitisieren.
Kompatibilität: In allen modernen Desktop-Browsern verfügbar. Auf Touch-Geräten wird HTML5-Drag-and-Drop erst in neueren Versionen (iOS Safari 15+, Chrome Android eingeschränkt) unterstützt. Ältere Internet-Explorer-Versionen kannten nur die Formate Text und URL.

Siehe auch

InputEvent.dataTransfer BlobEvent.data Element.attributes Event.isTrusted Event.target