new DataTransfer() — Methode · JavaScript-Referenz

Signatur

new DataTransfer()

Beschreibung

Der Konstruktor new DataTransfer() erzeugt ein leeres DataTransfer-Objekt ohne Daten, Dateien oder Typen. Normalerweise bekommt man ein solches Objekt nur über Events: event.dataTransfer bei Drag-and-Drop-Events oder event.clipboardData bei Zwischenablage-Events. Mit dem Konstruktor lässt es sich auch selbst anlegen.

In der Praxis braucht man ihn vor allem für zwei Dinge:

Dateilisten erstellen: FileList hat keinen öffentlichen Konstruktor. Über dataTransfer.items.add(file) und anschließend dataTransfer.files bekommt man trotzdem eine echte FileList, die man input.files zuweisen kann – etwa um einzelne Dateien aus einer Auswahl zu entfernen oder per Einfügen oder Drop erhaltene Dateien in ein Formularfeld zu übernehmen.
Events synthetisch erzeugen: Beim Testen (z. B. mit Jest/Playwright im Browser) lässt sich ein DragEvent oder ClipboardEvent mit einem vorbefüllten DataTransfer auslösen.

Ein selbst erzeugtes Objekt ist immer im Lese-/Schreibmodus. Man kann also setData(), getData(), clearData() und items.add() uneingeschränkt nutzen. Einen echten Drag-Vorgang des Betriebssystems löst es aber nicht aus, und auf die System-Zwischenablage greift es ebenfalls nicht zu.

Rückgabewert

Typ

DataTransfer

Beschreibung

Ein neues, leeres DataTransfer-Objekt: types und files sind leer, dropEffect ist "none", effectAllowed ist "none".

Beispiele

Datei aus einem Datei-Input entfernen

// <input type="file" id="upload" multiple>
const input = document.querySelector('#upload');

const removeFile = (index) => {
  const dt = new DataTransfer();
  [...input.files].forEach((file, i) => {
    if (i !== index) dt.items.add(file);
  });
  input.files = dt.files; // echte FileList zuweisen
  console.log(`Verbleibende Dateien: ${input.files.length}`);
};

// z. B. nach Auswahl von 3 Dateien:
removeFile(1);

Verbleibende Dateien: 2

Programmatisch erzeugte Datei einem Formularfeld zuweisen

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

const blob = new Blob(['id;name\n1;Anna\n'], { type: 'text/csv' });
const file = new File([blob], 'export.csv', { type: 'text/csv' });

const dt = new DataTransfer();
dt.items.add(file);
input.files = dt.files;

// Framework-Listener informieren
input.dispatchEvent(new Event('change', { bubbles: true }));
console.log(input.files[0].name, input.files[0].size);

export.csv 16

Drop-Event im Test simulieren

const dropZone = document.querySelector('#drop-zone');

dropZone.addEventListener('dragover', (e) => e.preventDefault());
dropZone.addEventListener('drop', (e) => {
  e.preventDefault();
  console.log('Text:', e.dataTransfer.getData('text/plain'));
  console.log('Dateien:', e.dataTransfer.files.length);
});

const dt = new DataTransfer();
dt.setData('text/plain', 'Hallo Welt');
dt.items.add(new File(['Inhalt'], 'notiz.txt', { type: 'text/plain' }));

dropZone.dispatchEvent(new DragEvent('drop', {
  bubbles: true,
  cancelable: true,
  dataTransfer: dt
}));

Text: Hallo Welt Dateien: 1

Eingefügte Bilder in ein Datei-Input übernehmen

const input = document.querySelector('#bilder');

document.addEventListener('paste', (e) => {
  const images = [...e.clipboardData.files]
    .filter((f) => f.type.startsWith('image/'));
  if (!images.length) return;

  const dt = new DataTransfer();
  [...input.files, ...images].forEach((f) => dt.items.add(f));
  input.files = dt.files;
  console.log(`${images.length} Bild(er) hinzugefügt`);
});

1 Bild(er) hinzugefügt

// Wichtig · Fallstricke

Kompatibilität: Der Konstruktor ist in allen aktuellen Browsern verfügbar. Ältere Safari-Versionen (vor 14.1) und der Internet Explorer unterstützen ihn nicht und werfen einen TypeError. Bei Bedarf vorher per typeof DataTransfer === 'function' bzw. mit try/catch prüfen.
Das Zuweisen von input.files löst kein change- oder input-Event aus. React, Vue und ähnliche Frameworks bemerken die Änderung nur, wenn man selbst ein Event auslöst.
dataTransfer.files ist eine Momentaufnahme. Spätere items.add()-Aufrufe tauchen erst nach erneutem Lesen von dt.files auf.
Synthetische Events sind nicht vertrauenswürdig (isTrusted === false). Sie starten keinen nativen Drag-Vorgang und schreiben nichts in die System-Zwischenablage. Für die Zwischenablage stattdessen die navigator.clipboard-API verwenden.
In Node.js und in jsdom gibt es DataTransfer nicht oder nur unvollständig. Für Tests ist ein echter Browser (Playwright, Cypress) oder ein Polyfill nötig.
Sicherheit: Dateien, die man selbst erzeugt oder übernimmt, müssen serverseitig genauso geprüft werden wie vom Nutzer ausgewählte. Auf file.type und den Dateinamen ist kein Verlass.

Siehe auch

DataTransfer DataTransfer.items DataTransfer.files DataTransfer.prototype.setData() DataTransferItemList.prototype.add() DragEvent FileList ClipboardEvent