FileList — Schnittstelle · JavaScript-Referenz

Signatur

interface FileList

Beschreibung

FileList ist eine schreibgeschützte, arrayähnliche Sammlung von File-Objekten. Man bekommt sie vor allem über die Eigenschaft files eines <input type="file">-Elements und über DataTransfer.files bei Drag-and-Drop. Außerdem liefert HTMLCanvasElement sie nicht; die Quelle ist fast immer eine Aktion der Nutzerin oder des Nutzers.

Die Schnittstelle ist sehr klein:

length: Anzahl der Dateien in der Liste (nur lesbar).
item(index): gibt das File an der Position index zurück oder null, wenn der Index außerhalb liegt.
Indexzugriff fileList[0]: entspricht item(0), liefert bei ungültigem Index aber undefined.
Iterierbar: for...of, Spread-Syntax und Array.from() funktionieren.

Weil FileList kein echtes Array ist, fehlen Methoden wie map(), filter() oder forEach(). Für solche Operationen wandelt man sie mit Array.from(fileList) oder [...fileList] in ein Array um. Die einzelnen Einträge sind File-Objekte (eine Unterklasse von Blob). Ihren Inhalt liest man mit file.text(), file.arrayBuffer() oder FileReader, oder man lädt sie per FormData und fetch() hoch.

Parameter

Name	Typ	Default	Beschreibung
$index Pflicht	number		Nur bei `item(index)`: nullbasierter Index der gewünschten Datei.

Beispiele

Ausgewählte Dateien eines Datei-Inputs auflisten

// HTML: <input type="file" id="upload" multiple>
const input = document.querySelector('#upload');

input.addEventListener('change', () => {
  const files = input.files; // FileList
  console.log(`Anzahl: ${files.length}`);

  for (const file of files) {
    console.log(`${file.name} – ${(file.size / 1024).toFixed(1)} KB – ${file.type || 'unbekannt'}`);
  }

  // Zugriff per Index bzw. item()
  console.log(files[0]?.name, files.item(99)); // item() liefert null bei ungültigem Index
});

Anzahl: 2 foto.jpg – 245.3 KB – image/jpeg bericht.pdf – 88.1 KB – application/pdf foto.jpg null

In ein Array umwandeln und nach Typ filtern

const input = document.querySelector('#upload');

input.addEventListener('change', () => {
  const bilder = Array.from(input.files)
    .filter((file) => file.type.startsWith('image/'))
    .filter((file) => file.size <= 5 * 1024 * 1024); // max. 5 MB

  console.log(bilder.map((f) => f.name));
});

["foto.jpg", "logo.png"]

Dateien per Drag-and-Drop mit fetch hochladen

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

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

dropZone.addEventListener('drop', async (event) => {
  event.preventDefault();
  const files = event.dataTransfer.files; // FileList

  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 von ${files.length} Datei(en): ${response.status}`);
});

Upload von 3 Datei(en): 200

Eigene FileList per DataTransfer erzeugen und zuweisen

// FileList hat keinen Konstruktor – DataTransfer ist der übliche Umweg
const input = document.querySelector('#upload');
const dt = new DataTransfer();
dt.items.add(new File(['Hallo Welt'], 'gruss.txt', { type: 'text/plain' }));

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

const inhalt = await input.files[0].text();
console.log(inhalt);

1 gruss.txt Hallo Welt

// Wichtig · Fallstricke

Kein Konstruktor: new FileList() wirft einen TypeError. Eine eigene Liste erzeugt man über new DataTransfer() und dataTransfer.files.
Schreibgeschützt: Man kann keine Einträge hinzufügen oder entfernen. Um eine Datei zu entfernen, baut man mit DataTransfer eine neue Liste und weist sie input.files zu.
Kein Array: files.map() oder files.forEach() gibt es nicht. Vorher mit Array.from() umwandeln.
Live-Bezug bei Inputs: input.files gibt immer die aktuelle Auswahl wieder. Wählt die Person neue Dateien aus, ändert sich der Inhalt. Wer die Liste später noch braucht, sollte sie in ein Array kopieren. Bei DataTransfer.files aus einem drop-Event ist die Liste nur während des Event-Handlers zuverlässig nutzbar.
Leerer Input: Wird nichts ausgewählt, ist files.length gleich 0. Bei Inputs, die nicht vom Typ file sind, ist input.files gleich null.
Sicherheit: file.type leitet sich nur aus der Dateiendung ab und ist nicht vertrauenswürdig. Dateityp und -größe müssen immer auf dem Server geprüft werden. Aus Datenschutzgründen stehen nur Dateiname und Metadaten zur Verfügung, nie der vollständige lokale Pfad.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Die Iterierbarkeit (for...of) und das Zuweisen an input.files funktionieren in aktuellen Versionen von Chrome, Firefox, Safari und Edge.

Siehe auch

File Blob FileReader DataTransfer HTMLInputElement.files FormData Array.from()