DataTransferItem.getAsFile() — Methode · JavaScript-Referenz

Signatur

DataTransferItem.prototype.getAsFile()

Beschreibung

Mit getAsFile() erhältst du aus einem DataTransferItem das zugehörige File-Objekt. Die Methode wird typischerweise im drop-Handler einer Drag-&-Drop-Zone oder im paste-Handler verwendet, wenn Nutzer Dateien, z. B. Bilder oder PDFs, in die Seite ziehen oder aus der Zwischenablage einfügen.

Ob ein Element eine Datei enthält, erkennst du an der Eigenschaft item.kind: Nur bei "file" liefert getAsFile() ein File. Bei kind === "string" ist der Rückgabewert null. Textdaten liest du in diesem Fall mit getAsString() aus.

Das zurückgegebene File erbt von Blob. Du kannst es also direkt mit file.text(), file.arrayBuffer() oder URL.createObjectURL(file) weiterverarbeiten oder per FormData hochladen.

Wichtig: Der Datenspeicher von DataTransfer ist nur während des drop- bzw. paste-Events lesbar (read/write-Modus bei dragstart, sonst protected). Rufe getAsFile() deshalb synchron im Handler auf und sichere die File-Objekte, bevor du asynchron weiterarbeitest.

Rückgabewert

Typ

File | null

Beschreibung

Ein File-Objekt, wenn kind gleich "file" ist, sonst null. Außerhalb von drop/paste (geschützter Modus) ist der Rückgabewert ebenfalls null.

Beispiele

Dateien in einer Drop-Zone entgegennehmen

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

// dragover muss abgebrochen werden, sonst feuert kein drop
dropZone.addEventListener('dragover', (event) => {
  event.preventDefault();
  event.dataTransfer.dropEffect = 'copy';
});

dropZone.addEventListener('drop', (event) => {
  event.preventDefault();

  const files = [...event.dataTransfer.items]
    .filter((item) => item.kind === 'file')
    .map((item) => item.getAsFile())
    .filter(Boolean);

  for (const file of files) {
    console.log(`${file.name} (${file.type}, ${file.size} Bytes)`);
  }
});

bericht.pdf (application/pdf, 48213 Bytes) foto.jpg (image/jpeg, 1203344 Bytes)

Bild aus der Zwischenablage einfügen und anzeigen

document.addEventListener('paste', (event) => {
  for (const item of event.clipboardData.items) {
    if (item.kind === 'file' && item.type.startsWith('image/')) {
      const file = item.getAsFile();
      const img = document.createElement('img');
      img.src = URL.createObjectURL(file);
      img.onload = () => URL.revokeObjectURL(img.src);
      document.body.append(img);
      console.log('Bild eingefügt:', file.type);
    }
  }
});

Bild eingefügt: image/png

Dateien synchron sichern, dann asynchron hochladen

const dropZone = document.querySelector('#upload');
dropZone.addEventListener('dragover', (e) => e.preventDefault());

dropZone.addEventListener('drop', async (event) => {
  event.preventDefault();

  // Synchron auslesen – nach dem ersten await ist der Datenspeicher gesperrt
  const files = [...event.dataTransfer.items]
    .map((item) => item.getAsFile())
    .filter((file) => file !== null);

  const formData = new FormData();
  files.forEach((file) => formData.append('dateien', file, file.name));

  const response = await fetch('/api/upload', { method: 'POST', body: formData });
  console.log('Upload-Status:', response.status);
});

Upload-Status: 200

// Wichtig · Fallstricke

Nur synchron im Event nutzbar: Nach einem await oder in einem setTimeout ist die DataTransferItemList leer bzw. geschützt, und getAsFile() liefert null. Speichere die File-Objekte also vorher in einem Array.
Kein Drop ohne dragover: Ohne event.preventDefault() im dragover-Handler löst der Browser kein drop aus und öffnet die Datei stattdessen selbst.
Ordner: Wird ein Verzeichnis gezogen, liefert getAsFile() je nach Browser ein unbrauchbares File (Größe 0 bzw. Lesefehler). Zum Durchlaufen von Ordnern nutzt du webkitGetAsEntry() oder getAsFileSystemHandle() (nur Chromium).
MIME-Typ nicht vertrauen: file.type wird aus der Dateiendung abgeleitet und kann leer oder gefälscht sein. Prüfe Dateien vor dem Upload daher serverseitig.
Die Methode wird in allen modernen Browsern unterstützt. In sehr alten Browsern wie dem Internet Explorer fehlt dataTransfer.items. Als Rückfallebene dient dort dataTransfer.files.

Siehe auch

File DataTransferItem.getAsString() DataTransferItem.webkitGetAsEntry() DataTransferItem.getAsFileSystemHandle() DataTransferItemList.add()