DataTransferItemList.add() — Methode · JavaScript-Referenz

Signatur

DataTransferItemList.prototype.add(data, type) | DataTransferItemList.prototype.add(file)

Beschreibung

Mit add() fügst du einem DataTransfer-Objekt über dessen Eigenschaft items neue Einträge hinzu. Die Methode gibt es in zwei Formen: add(data, type) legt einen String-Eintrag (kind === "string") mit dem angegebenen MIME-Typ an, add(file) einen Datei-Eintrag (kind === "file").

Typische Einsätze sind der dragstart-Handler, in dem du festlegst, was beim Ziehen mitgegeben wird (z. B. Klartext und HTML parallel), die Ereignisse copy und cut sowie ein selbst erzeugtes Objekt per new DataTransfer(). Mit Letzterem kannst du programmatisch eine FileList bauen und sie einem <input type="file"> über input.files zuweisen.

Schreiben kannst du nur, solange der Drag-Datenspeicher im read/write-Modus ist. Das gilt während dragstart, bei copy/cut und immer bei selbst erzeugten DataTransfer-Objekten. In dragover, drop usw. ist die Liste geschützt oder nur lesbar. Dort gibt add() null zurück und ändert nichts.

Parameter

Name	Typ	Beschreibung
$data Pflicht	string	Die Zeichenkette für den neuen Eintrag (erste Form). Ein Nicht-String wird in einen String umgewandelt.
$type Pflicht	string	MIME-Typ der Daten, z. B. `"text/plain"`, `"text/html"` oder `"text/uri-list"`. Wird in Kleinbuchstaben umgewandelt. Nur bei der String-Form nötig.
$file Pflicht	File	Ein `File`-Objekt (zweite Form). Der Eintrag bekommt `kind = "file"`, und als Typ wird der `file.type` der Datei übernommen.

Rückgabewert

Typ

DataTransferItem | null

Beschreibung

Das neu angelegte DataTransferItem. null, wenn der Datenspeicher nicht im read/write-Modus ist.

Beispiele

Text und HTML beim Drag-Start mitgeben

const card = document.querySelector('#card');
card.draggable = true;

card.addEventListener('dragstart', (event) => {
  const { items } = event.dataTransfer;
  items.add(card.textContent.trim(), 'text/plain');
  items.add(card.outerHTML, 'text/html');
  console.log('Einträge:', items.length);
});

Einträge: 2

Dateien programmatisch in ein File-Input setzen

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;
console.log([...input.files].map((f) => f.name));

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

Doppelten MIME-Typ abfangen

const dt = new DataTransfer();
dt.items.add('erste Version', 'text/plain');

try {
  dt.items.add('zweite Version', 'text/plain');
} catch (err) {
  console.log(err.name);
}

// Überschreiben geht einfacher mit setData():
dt.setData('text/plain', 'zweite Version');
console.log(dt.getData('text/plain'));

NotSupportedError zweite Version

Rückgabewert außerhalb des Schreibmodus prüfen

const zone = document.querySelector('#dropzone');
zone.addEventListener('dragover', (e) => e.preventDefault());
zone.addEventListener('drop', (event) => {
  event.preventDefault();
  const item = event.dataTransfer.items.add('x', 'text/plain');
  console.log(item); // bei drop nur lesbar
});

null

// Wichtig · Fallstricke

Doppelte Typen: Gibt es schon einen String-Eintrag mit demselben MIME-Typ, wirft add(data, type) eine DOMException vom Typ NotSupportedError. Zum Ersetzen nimmst du DataTransfer.setData() oder entfernst den alten Eintrag vorher mit remove(). Mehrere Datei-Einträge mit demselben Typ sind dagegen erlaubt.
Schreibmodus: Nur in dragstart, copy/cut und bei new DataTransfer() ist die Liste beschreibbar. Sonst liefert add() stillschweigend null, ohne einen Fehler zu werfen.
Falsche Argumente: Ein einzelnes Argument, das kein File ist, führt zu einem TypeError.
Kompatibilität: Den Konstruktor new DataTransfer() gibt es in Safari erst ab 14.1. Ältere Safari-Versionen können deshalb keine input.files programmatisch setzen.
Sicherheit: Mitgegebenes text/html kann das Ziel (z. B. ein Editor mit contenteditable) übernehmen. Ziehe keine vertraulichen Daten in die Liste, und bereinige empfangenes HTML beim Drop, bevor du es per innerHTML einfügst (XSS).

Siehe auch

DataTransferItemList.clear() DataTransferItemList.remove() DataTransfer.getData() DataTransfer.setData() DataTransferItem.getAsFile()