DataTransfer — Schnittstelle · JavaScript-Referenz

Signatur

interface DataTransfer

Beschreibung

DataTransfer ist der Datencontainer hinter Drag-and-Drop und den Zwischenablage-Ereignissen. Den Container bekommt man meist nicht selbst erzeugt, sondern über die Eigenschaft event.dataTransfer eines DragEvent (dragstart, dragover, drop …) oder über event.clipboardData eines ClipboardEvent (copy, cut, paste).

Wichtige Mitglieder:

setData(format, data) / getData(format) / clearData([format]) – Zeichenketten unter einem MIME-Typ wie text/plain, text/html oder text/uri-list speichern, lesen und löschen.
files – eine FileList mit gezogenen oder eingefügten Dateien.
items – eine DataTransferItemList mit feinerem Zugriff auf einzelne Einträge (auch Dateien und Verzeichnisse).
types – ein schreibgeschütztes Array der vorhandenen Formate.
dropEffect und effectAllowed – steuern, welche Operation (copy, move, link, none) angezeigt bzw. erlaubt ist.
setDragImage(image, x, y) – legt ein eigenes Vorschaubild für das Ziehen fest.

Mit dem Konstruktor new DataTransfer() lässt sich außerdem ein leeres Objekt erzeugen. Das ist vor allem nützlich, um programmatisch eine FileList zusammenzustellen und sie einem <input type="file"> zuzuweisen, oder um Drag-Ereignisse in Tests zu simulieren.

Beachte das Schutzmodell: Während dragstart ist das Objekt beschreibbar, bei drop nur lesbar, und dazwischen (dragenter, dragover) ist es geschützt – dort sieht man nur types, nicht die eigentlichen Daten.

Parameter

Name	Typ	Beschreibung
$(Konstruktor) new DataTransfer()	—	Der Konstruktor nimmt keine Argumente an und erzeugt ein leeres, beschreibbares `DataTransfer`-Objekt.
$format Pflicht	string	Bei `setData`/`getData`/`clearData`: MIME-Typ der Daten, z. B. `"text/plain"` oder `"application/json"`. `"text"` und `"url"` werden als `text/plain` bzw. `text/uri-list` behandelt.
$data Pflicht	string	Bei `setData`: die zu speichernde Zeichenkette. Objekte vorher mit `JSON.stringify()` umwandeln.
$image, xOffset, yOffset Pflicht	Element, number, number	Bei `setDragImage`: Element (meist `<img>` oder `<canvas>`) als Vorschaubild sowie der Versatz des Mauszeigers zum Bild.

Rückgabewert

Typ

DataTransfer

Beschreibung

Der Konstruktor liefert ein neues, leeres DataTransfer-Objekt. getData() gibt einen string zurück (leer, wenn das Format fehlt oder geschützt ist), setData(), clearData() und setDragImage() geben undefined zurück.

Beispiele

Drag-and-Drop einer Aufgabe zwischen Listen

// HTML: <li draggable="true" id="task-42">Bericht schreiben</li>
//       <ul id="erledigt"></ul>
const task = document.getElementById('task-42');
const ziel = document.getElementById('erledigt');

task.addEventListener('dragstart', (event) => {
  event.dataTransfer.setData('application/json', JSON.stringify({ id: task.id }));
  event.dataTransfer.setData('text/plain', task.textContent);
  event.dataTransfer.effectAllowed = 'move';
});

ziel.addEventListener('dragover', (event) => {
  // Ohne preventDefault() ist kein Drop möglich
  if (event.dataTransfer.types.includes('application/json')) {
    event.preventDefault();
    event.dataTransfer.dropEffect = 'move';
  }
});

ziel.addEventListener('drop', (event) => {
  event.preventDefault();
  const { id } = JSON.parse(event.dataTransfer.getData('application/json'));
  ziel.append(document.getElementById(id));
  console.log(`Verschoben: ${id}`);
});

Verschoben: task-42

Dateien per Drop entgegennehmen

const dropzone = document.querySelector('#dropzone');

dropzone.addEventListener('dragover', (event) => event.preventDefault());

dropzone.addEventListener('drop', async (event) => {
  event.preventDefault();
  for (const file of event.dataTransfer.files) {
    console.log(`${file.name} (${file.type}, ${file.size} Bytes)`);
    if (file.type.startsWith('text/')) {
      console.log(await file.text());
    }
  }
});

notizen.txt (text/plain, 128 Bytes) ...

FileList programmatisch per Konstruktor erzeugen

const input = document.querySelector('input[type="file"]');

const dt = new DataTransfer();
dt.items.add(new File(['Hallo Welt'], 'gruss.txt', { type: 'text/plain' }));
dt.items.add(new File(['{"a":1}'], 'daten.json', { type: 'application/json' }));

input.files = dt.files; // FileList zuweisen
console.log(input.files.length, [...input.files].map((f) => f.name));

2 ["gruss.txt", "daten.json"]

Kopieren abfangen und Text anreichern

document.addEventListener('copy', (event) => {
  const auswahl = document.getSelection().toString();
  event.clipboardData.setData('text/plain', `${auswahl}\n\nQuelle: ${location.href}`);
  event.preventDefault(); // Standardverhalten unterdrücken
});

document.addEventListener('paste', (event) => {
  const text = event.clipboardData.getData('text/plain');
  console.log('Eingefügt:', text);
});

Eingefügt: ...

// Wichtig · Fallstricke

Drop braucht preventDefault(): Wird in dragover (und idealerweise dragenter) nicht event.preventDefault() aufgerufen, löst der Browser kein drop aus. Im drop-Handler verhindert preventDefault(), dass der Browser z. B. eine gezogene Datei direkt öffnet.
Geschützter Modus: In dragenter/dragover liefert getData() einen leeren String. Entscheide dort anhand von types, ob ein Drop erlaubt ist.
Nicht asynchron weiterverwenden: Das Objekt ist nur während des Ereignisses gültig. Nach einem await oder in einem setTimeout sind die Daten meist weg – vorher auslesen bzw. getAsFile()/files in Variablen sichern.
Sicherheit: Gezogene oder eingefügte Inhalte stammen aus fremden Quellen. text/html nie ungeprüft per innerHTML einfügen (XSS-Gefahr) – vorher bereinigen (z. B. mit DOMPurify) oder textContent verwenden.
Nur Zeichenketten: setData() wandelt alles in Strings um; Objekte mit JSON.stringify() serialisieren. Eigene MIME-Typen funktionieren innerhalb der Seite, werden an andere Anwendungen aber oft nicht weitergegeben.
Kompatibilität: Der Konstruktor fehlt im Internet Explorer und in älteren Safari-Versionen (vor 14.1). Auf Touch-Geräten wird die native Drag-and-Drop-API nur teilweise unterstützt (iOS erst ab Safari 15). Für programmatischen Zugriff auf die Zwischenablage ohne Ereignis gibt es die asynchrone navigator.clipboard-API.

Siehe auch

DataTransferItem SVGTransform BatteryManager DOMParser DataCue DelegatedInkTrailPresenter