DataTransferItem.kind — Eigenschaft · JavaScript-Referenz

Signatur

DataTransferItem.kind

Beschreibung

Die Eigenschaft kind eines DataTransferItem sagt dir, welche Art von Daten ein Element bei Drag-and-Drop oder beim Einfügen aus der Zwischenablage enthält. Es gibt genau zwei mögliche Werte: "string" für Text wie text/plain, text/html oder text/uri-list und "file" für Dateien, etwa Bilder aus dem Dateimanager oder aus der Zwischenablage.

Von kind hängt ab, wie du an den Inhalt kommst: Bei "string" liest du den Wert asynchron mit getAsString(callback) aus. Bei "file" bekommst du mit getAsFile() ein File-Objekt. Rufst du die falsche Methode auf, erhältst du null, oder der Callback wird gar nicht aufgerufen.

In der Praxis prüfst du kind in Handlern für drop und paste, meist zusammen mit type (dem MIME-Typ). So kannst du zum Beispiel nur eingefügte Bilder verarbeiten und Text ignorieren oder gezogene Links anders behandeln als Dateien.

Rückgabewert

Typ

"string" | "file"

Beschreibung

"string", wenn das Element Text enthält, oder "file", wenn es eine Datei enthält. Ist das DataTransfer-Objekt nicht mehr im passenden Modus (z. B. nachdem der Event-Handler beendet ist), ist der Wert ein leerer String "".

Beispiele

Abgelegte Elemente nach Art unterscheiden

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

// dragover muss verhindert werden, sonst wird drop nicht ausgelöst
dropZone.addEventListener('dragover', (event) => event.preventDefault());

dropZone.addEventListener('drop', (event) => {
  event.preventDefault();
  for (const item of event.dataTransfer.items) {
    if (item.kind === 'file') {
      const file = item.getAsFile();
      console.log(`Datei: ${file.name} (${file.size} Bytes)`);
    } else if (item.kind === 'string') {
      item.getAsString((text) => {
        console.log(`Text (${item.type}): ${text}`);
      });
    }
  }
});

Datei: foto.jpg (204800 Bytes)

Nur eingefügte Bilder aus der Zwischenablage verarbeiten

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

  if (images.length === 0) return; // normales Einfügen von Text zulassen

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

1 Bild(er) eingefügt

Strings asynchron mit Promise auslesen

const readString = (item) =>
  new Promise((resolve) => item.getAsString(resolve));

document.addEventListener('drop', async (event) => {
  event.preventDefault();
  // Werte synchron einsammeln, bevor der Handler endet
  const stringItems = [...event.dataTransfer.items]
    .filter((item) => item.kind === 'string');
  const entries = await Promise.all(
    stringItems.map(async (item) => [item.type, await readString(item)])
  );
  console.log(Object.fromEntries(entries));
});
document.addEventListener('dragover', (e) => e.preventDefault());

{ 'text/plain': 'https://example.com', 'text/uri-list': 'https://example.com' }

// Wichtig · Fallstricke

Nur während des Events gültig: Nachdem der drop- bzw. paste-Handler beendet ist, wird der DataTransfer ungültig. kind liefert dann "", und getAsFile() gibt null zurück. Lies Elemente deshalb synchron aus, bevor du ein await verwendest. getAsString() muss ebenfalls noch im Handler aufgerufen werden.
Schutzmodus: Bei dragstart, dragenter und dragover sind kind und type lesbar, der eigentliche Inhalt aber nicht. Das kannst du nutzen, um Drop-Ziele schon während des Ziehens hervorzuheben (z. B. „hier sind Dateien erlaubt“).
Nur lesbar: Eine Zuweisung an kind wird ignoriert (im Strict Mode gibt es einen TypeError). Die Art ergibt sich daraus, wie das Element angelegt wurde, z. B. mit items.add(string, type) oder items.add(file).
Ordner: Auch gezogene Verzeichnisse haben kind === "file". Zum Unterscheiden gibt es webkitGetAsEntry() bzw. getAsFileSystemHandle(), die aber nicht überall verfügbar sind.
Kompatibilität: DataTransferItem wird in allen modernen Browsern unterstützt (Chrome, Edge, Firefox 50+, Safari 11.1+). Den Internet Explorer brauchst du nicht zu berücksichtigen. Dort gab es nur dataTransfer.files.

Siehe auch

DataTransferItem.type DataTransfer.items DataTransfer.files DataTransfer.types DataTransferItemList.length