FileList.item() — Methode · JavaScript-Referenz

Signatur

FileList.prototype.item(index)

Beschreibung

Die Methode item() liefert die Datei an einer bestimmten Position einer FileList. Eine FileList bekommt man z. B. über die Eigenschaft files eines <input type="file">-Elements oder über DataTransfer.files bei Drag & Drop.

In der Praxis greift man meist mit der Klammerschreibweise fileList[i] zu, die genauso funktioniert. Der Unterschied zeigt sich bei ungültigen Indizes: item() gibt null zurück, der Klammerzugriff dagegen undefined. item() ist nützlich, wenn man ausdrücklich auf null prüfen will oder Code schreibt, der sich an die DOM-Konventionen hält (vergleichbar mit NodeList.item()).

Eine FileList ist kein echtes Array. Sie hat zwar length und ist iterierbar (for...of, Spread-Syntax), bietet aber keine Array-Methoden wie map() oder filter(). Dafür wandelt man sie vorher mit Array.from() um.

Parameter

Name	Typ	Default	Beschreibung
$index Pflicht	number		Nullbasierter Index der gewünschten Datei. Der Wert wird in eine vorzeichenlose 32-Bit-Ganzzahl umgewandelt (`unsigned long`).

Rückgabewert

Typ

File | null

Beschreibung

Das File-Objekt am angegebenen Index oder null, wenn index größer oder gleich length ist.

Beispiele

Erste ausgewählte Datei auslesen

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

input.addEventListener('change', () => {
  const file = input.files.item(0);
  if (file === null) {
    console.log('Keine Datei ausgewählt');
    return;
  }
  console.log(`${file.name} – ${file.size} Bytes – ${file.type}`);
});

bericht.pdf – 48213 Bytes – application/pdf

Alle Dateien einer Mehrfachauswahl durchlaufen

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

input.addEventListener('change', () => {
  const { files } = input;
  for (let i = 0; i < files.length; i++) {
    const file = files.item(i);
    console.log(`${i + 1}. ${file.name}`);
  }
});

1. urlaub.jpg 2. strand.png

Drag & Drop mit Unterschied null vs. undefined

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

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

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

  console.log(files.item(0)?.name); // Name der ersten Datei
  console.log(files.item(99));      // null (außerhalb des Bereichs)
  console.log(files[99]);           // undefined (Klammerzugriff)

  // Für Array-Methoden vorher umwandeln
  const totalSize = Array.from(files).reduce((sum, f) => sum + f.size, 0);
  console.log(`Gesamt: ${totalSize} Bytes`);
});

notizen.txt null undefined Gesamt: 1024 Bytes

// Wichtig · Fallstricke

null statt undefined: Bei ungültigem Index gibt item() null zurück, files[i] aber undefined. Strikte Vergleiche (=== undefined) liefern deshalb unterschiedliche Ergebnisse.
Negative Indizes: Weil der Wert in eine vorzeichenlose 32-Bit-Ganzzahl umgewandelt wird, ergibt item(-1) einen sehr großen Index und damit null, nicht die letzte Datei. Anders als bei Array.prototype.at() gibt es keinen Rückwärtszugriff.
Fehlendes Argument: Ein Aufruf von item() ohne Argument löst einen TypeError aus.
Momentaufnahme: Wählt der Nutzer neue Dateien aus, ersetzt der Browser input.files durch eine neue FileList. Deshalb bei jedem change-Ereignis neu auslesen.
Kompatibilität: Wird von allen modernen Browsern unterstützt, auch von alten Versionen des Internet Explorers ab IE 10.

Siehe auch

FileList FileList.length File HTMLInputElement.files DataTransfer.files FileReader Array.from()