DataTransfer.files — Eigenschaft · JavaScript-Referenz

Signatur

get DataTransfer.files

Beschreibung

DataTransfer.files gibt eine FileList zurück, die alle Dateien enthält, die der Nutzer per Drag-and-Drop auf die Seite gezogen oder über die Zwischenablage eingefügt hat. Jeder Eintrag ist ein File-Objekt, das du mit FileReader, file.text(), file.arrayBuffer() oder per FormData weiterverarbeiten kannst.

Typische Einsatzorte sind Upload-Dropzones (im drop-Event über event.dataTransfer.files) und das Einfügen von Bildern aus der Zwischenablage (im paste-Event über event.clipboardData.files). Enthält die Operation keine Dateien, ist die Liste leer (length === 0).

Wichtig: Aus Sicherheitsgründen ist der Inhalt nur im drop-Event (bzw. paste) lesbar. In dragenter, dragover und dragleave befindet sich der Datenspeicher im geschützten Modus – files ist dort leer. Um schon beim Ziehen zu prüfen, ob Dateien dabei sind, nutzt man dataTransfer.types.includes("Files").

Die FileList ist kein echtes Array. Für map, filter usw. wandelt man sie mit Array.from() oder dem Spread-Operator um; for...of funktioniert direkt.

Rückgabewert

Typ

FileList

Beschreibung

Eine FileList mit den File-Objekten der Operation. Leer, wenn keine Dateien übertragen werden oder der Zugriff außerhalb von drop/paste erfolgt.

Beispiele

Einfache Dropzone für Datei-Uploads

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

// dragover muss verhindert werden, sonst ist drop nicht möglich
dropzone.addEventListener('dragover', (event) => {
  event.preventDefault();
  event.dataTransfer.dropEffect = 'copy';
});

dropzone.addEventListener('drop', (event) => {
  event.preventDefault(); // verhindert, dass der Browser die Datei öffnet
  const { files } = event.dataTransfer;
  for (const file of files) {
    console.log(`${file.name} – ${file.type || 'unbekannt'} – ${file.size} Bytes`);
  }
});

bericht.pdf – application/pdf – 48213 Bytes foto.jpg – image/jpeg – 1204551 Bytes

Gedroppte Bilder filtern und hochladen

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

dropzone.addEventListener('dragover', (e) => e.preventDefault());

dropzone.addEventListener('drop', async (event) => {
  event.preventDefault();
  const images = Array.from(event.dataTransfer.files)
    .filter((file) => file.type.startsWith('image/'));

  if (images.length === 0) {
    console.warn('Keine Bilder gefunden');
    return;
  }

  const formData = new FormData();
  images.forEach((img) => formData.append('images[]', img, img.name));

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

Upload-Status: 200

Screenshot aus der Zwischenablage einfügen

document.addEventListener('paste', async (event) => {
  const [file] = event.clipboardData.files;
  if (!file || !file.type.startsWith('image/')) return;

  const url = URL.createObjectURL(file);
  const img = document.createElement('img');
  img.src = url;
  img.onload = () => URL.revokeObjectURL(url);
  document.body.append(img);
  console.log('Bild eingefügt:', file.type);
});

Bild eingefügt: image/png

Beim Ziehen prüfen, ob Dateien dabei sind

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

dropzone.addEventListener('dragenter', (event) => {
  // files ist hier noch leer – daher types prüfen
  const hasFiles = event.dataTransfer.types.includes('Files');
  console.log('files.length:', event.dataTransfer.files.length, '| Dateien?', hasFiles);
  dropzone.classList.toggle('is-active', hasFiles);
});

dropzone.addEventListener('dragleave', () => dropzone.classList.remove('is-active'));

files.length: 0 | Dateien? true

// Wichtig · Fallstricke

Nur im drop-/paste-Event lesbar: In dragenter/dragover ist files immer leer (geschützter Modus). Nutze dort dataTransfer.types.includes("Files").
preventDefault() nicht vergessen: Ohne preventDefault() in dragover wird drop gar nicht ausgelöst; ohne preventDefault() in drop öffnet der Browser die Datei und verlässt die Seite.
Ordner: Gezogene Verzeichnisse erscheinen als Eintrag mit size 0 bzw. leerem type und lassen sich nicht auslesen. Für Ordnerinhalte dataTransfer.items mit webkitGetAsEntry() oder getAsFileSystemHandle() verwenden.
Kein Array: FileList besitzt kein map/filter – vorher Array.from() nutzen. Die Liste ist zudem nur zum Zeitpunkt des Events gültig; bei asynchroner Verarbeitung die File-Objekte vorher in ein Array kopieren.
Sicherheit: file.type wird aus der Dateiendung abgeleitet und ist nicht vertrauenswürdig. Dateityp und -größe immer serverseitig prüfen; Dateinamen niemals ungefiltert per innerHTML ausgeben (XSS).
Kompatibilität: In allen modernen Browsern unterstützt. Auf Mobilgeräten ist Drag-and-Drop von Dateien nur eingeschränkt verfügbar (z. B. iPadOS) – immer ein <input type="file"> als Alternative anbieten.

Siehe auch

File DataTransfer.items DataTransfer.types DataTransfer.dropEffect DataTransfer.effectAllowed