DataTransferItemList — Schnittstelle · JavaScript-Referenz

Signatur

interface DataTransferItemList

Beschreibung

DataTransferItemList bekommt man über DataTransfer.items. Das DataTransfer-Objekt selbst liefern die Ereignisse dragstart, dragover, drop (als event.dataTransfer) sowie paste, copy und cut (als event.clipboardData). Jeder Eintrag der Liste ist ein DataTransferItem und steht entweder für einen Text (kind === "string") oder für eine Datei (kind === "file").

Die Schnittstelle bietet mehr als die ältere API mit DataTransfer.setData()/getData() und DataTransfer.files. Man kann Einträge gezielt hinzufügen, entfernen und durchlaufen. Man kann den MIME-Typ jedes Eintrags prüfen, bevor man die Daten liest. Und über DataTransferItem.webkitGetAsEntry() kommt man an ganze Verzeichnisse heran.

Mitglieder der Schnittstelle:

length: Anzahl der Einträge (nur lesbar).
add(data, type) / add(file): Fügt einen Text mit MIME-Typ oder ein File hinzu. Rückgabewert ist das neue DataTransferItem oder null.
remove(index): Entfernt den Eintrag an der angegebenen Position.
clear(): Entfernt alle Einträge.
[index]: Zugriff auf einen Eintrag über den Index, wie bei einem Array.

Die Liste ist kein echtes Array. Methoden wie map oder filter fehlen. Man wandelt sie deshalb mit Array.from() um oder durchläuft sie mit einer for-Schleife über den Index.

Parameter

Name	Typ	Beschreibung
$data Pflicht	string \| File	Für `add()`: ein Text (dann ist `type` Pflicht) oder ein `File`-Objekt.
$type	string	MIME-Typ des Textes für `add(data, type)`, z. B. `"text/plain"` oder `"text/uri-list"`. Wird bei `add(file)` nicht angegeben.
$index Pflicht	number	Position des Eintrags für `remove(index)` bzw. für den Zugriff über `items[index]`.

Rückgabewert

Typ

DataTransferItemList

Beschreibung

DataTransfer.items gibt eine Instanz dieser Liste zurück. Ergebnisse der Methoden: add() liefert DataTransferItem | null, remove() und clear() liefern undefined.

Beispiele

Abgelegte Dateien und Texte beim drop auswerten

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

// dragover muss abgebrochen werden, sonst wird drop nie ausgelöst
zone.addEventListener('dragover', (event) => event.preventDefault());

zone.addEventListener('drop', (event) => {
  event.preventDefault();
  const { items } = event.dataTransfer;

  for (const item of Array.from(items)) {
    if (item.kind === 'file') {
      const file = item.getAsFile();
      console.log(`Datei: ${file.name} (${file.type}, ${file.size} Bytes)`);
    } else if (item.kind === 'string' && item.type === 'text/uri-list') {
      item.getAsString((url) => console.log('Link:', url));
    }
  }
});

Datei: foto.png (image/png, 48213 Bytes)

Eigene Daten beim dragstart hinzufügen

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

card.addEventListener('dragstart', (event) => {
  const { items } = event.dataTransfer;
  items.clear();
  items.add(card.textContent.trim(), 'text/plain');
  items.add(JSON.stringify({ id: card.dataset.id }), 'application/json');
  console.log('Anzahl Einträge:', items.length);
});

Anzahl Einträge: 2

Bilder aus der Zwischenablage einfügen

document.addEventListener('paste', (event) => {
  const images = Array.from(event.clipboardData.items)
    .filter((item) => item.kind === 'file' && item.type.startsWith('image/'))
    .map((item) => item.getAsFile());

  for (const img of images) {
    const el = document.createElement('img');
    el.src = URL.createObjectURL(img);
    document.body.append(el);
  }
  console.log(`${images.length} Bild(er) eingefügt`);
});

1 Bild(er) eingefügt

Dateiliste für ein <input type="file"> zusammenstellen

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(['{}'], 'daten.json', { type: 'application/json' }));
dt.items.remove(0); // gruss.txt wieder entfernen

input.files = dt.files;
console.log(input.files.length, input.files[0].name);

1 daten.json

// Wichtig · Fallstricke

Schutzmodus: Während dragover und dragenter ist die Liste geschützt. kind und type lassen sich lesen, der Inhalt aber nicht: getAsFile() liefert null. Den Inhalt bekommt man erst im drop-Ereignis.
Nur lesbar außerhalb von dragstart/copy/cut: Wer beim drop add(), remove() oder clear() aufruft, löst entweder eine InvalidStateError-Ausnahme aus oder die Änderung wird still ignoriert.
Zugriff nur synchron: Die Einträge sind nur während des Ereignisses gültig. Wer die Daten nach einem await lesen will, bekommt nichts mehr. Deshalb die Dateien bzw. getAsString()-Aufrufe sofort im Handler auslesen und zwischenspeichern.
add(data, type) wirft eine NotSupportedError-Ausnahme, wenn schon ein Text mit demselben MIME-Typ vorhanden ist.
getAsString() arbeitet mit einem Callback und gibt kein Promise zurück. Bei Bedarf selbst in ein Promise einpacken.
Der Konstruktor new DataTransfer() wird in Safari erst ab Version 14.1 unterstützt. Im Internet Explorer gibt es DataTransferItemList nicht.

Siehe auch

File DataTransferItem DataTransfer SVGTransformList RTCTransformEvent