File — Schnittstelle · JavaScript-Referenz

Signatur

interface File extends Blob

Beschreibung

Die Schnittstelle File beschreibt eine Datei. Sie liefert Metadaten wie name, size, type und lastModified und erlaubt Zugriff auf den Inhalt. Weil File von Blob erbt, stehen alle Blob-Methoden zur Verfügung: text(), arrayBuffer(), stream(), slice() und seit Kurzem auch bytes().

Meistens bekommt man File-Objekte nicht über den Konstruktor, sondern aus einer FileList: vom Eingabefeld <input type="file">, aus DataTransfer.files bei Drag & Drop, aus der Zwischenablage oder über die File System Access API (FileSystemFileHandle.getFile()). Mit new File(bits, name, options) lassen sich Dateien aber auch direkt im Speicher erzeugen, etwa um erzeugte Inhalte hochzuladen oder zum Download anzubieten.

Typische Einsatzfälle sind eine Vorschau vor dem Hochladen (über URL.createObjectURL()), Prüfungen von Größe und Typ auf dem Client, das Einlesen von CSV- oder JSON-Dateien direkt im Browser und Uploads per FormData und fetch(). Überall, wo ein Blob erwartet wird, kann man auch ein File übergeben.

Parameter

Name	Typ	Default	Beschreibung
$fileBits Pflicht	Array<ArrayBuffer\|TypedArray\|DataView\|Blob\|string>		Iterierbares Objekt mit den Inhaltsteilen, die hintereinandergehängt werden. Zeichenketten werden als UTF-8 kodiert.
$fileName Pflicht	string		Dateiname, z. B. `"bericht.txt"`. Verfügbar über `file.name`.
$options	{ type?: string, lastModified?: number, endings?: "transparent"\|"native" }	{}	`type`: MIME-Typ (Standard: `""`). `lastModified`: Zeitstempel in Millisekunden (Standard: `Date.now()`). `endings`: mit `"native"` werden Zeilenumbrüche in Zeichenketten an das Betriebssystem angepasst.

Rückgabewert

Typ

File

Beschreibung

Ein neues File-Objekt mit den Eigenschaften name, size, type, lastModified und webkitRelativePath sowie allen Methoden von Blob.

Beispiele

Datei im Speicher erzeugen und auslesen

const file = new File(
  [JSON.stringify({ name: 'Anna', alter: 32 }, null, 2)],
  'nutzer.json',
  { type: 'application/json', lastModified: Date.now() }
);

console.log(file.name, file.type, file.size);
console.log(file instanceof Blob);

const daten = JSON.parse(await file.text());
console.log(daten.name);

nutzer.json application/json 38 true Anna

Dateiauswahl prüfen und Bildvorschau anzeigen

// HTML: <input type="file" id="upload" accept="image/*" multiple> <div id="vorschau"></div>
const input = document.querySelector('#upload');
const vorschau = document.querySelector('#vorschau');
const MAX_GROESSE = 5 * 1024 * 1024; // 5 MB

input.addEventListener('change', () => {
  for (const file of input.files) {
    if (!file.type.startsWith('image/')) {
      console.warn(`${file.name}: kein Bild`);
      continue;
    }
    if (file.size > MAX_GROESSE) {
      console.warn(`${file.name}: zu groß (${(file.size / 1e6).toFixed(1)} MB)`);
      continue;
    }
    const img = document.createElement('img');
    img.src = URL.createObjectURL(file);
    img.onload = () => URL.revokeObjectURL(img.src); // Speicher freigeben
    img.alt = file.name;
    vorschau.append(img);
    console.log(`${file.name}, geändert am ${new Date(file.lastModified).toLocaleDateString('de-DE')}`);
  }
});

Datei per fetch und FormData hochladen

const hochladen = async (file) => {
  const formData = new FormData();
  formData.append('dokument', file, file.name);

  const res = await fetch('/api/upload', { method: 'POST', body: formData });
  if (!res.ok) throw new Error(`Upload fehlgeschlagen: ${res.status}`);
  return res.json();
};

const csv = new File(['id;name\n1;Anna\n2;Ben\n'], 'export.csv', { type: 'text/csv' });
const ergebnis = await hochladen(csv);
console.log(ergebnis);

Große Datei stückweise lesen

const zeilenZaehlen = async (file) => {
  const reader = file.stream().pipeThrough(new TextDecoderStream()).getReader();
  let zeilen = 0;
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    zeilen += value.split('\n').length - 1;
  }
  return zeilen;
};

const log = new File(['a\nb\nc\n'], 'server.log', { type: 'text/plain' });
console.log(await zeilenZaehlen(log));

3

// Wichtig · Fallstricke

Dem MIME-Typ nicht trauen: file.type errät der Browser meist aus der Dateiendung. Er kann leer sein ("") oder bewusst gefälscht werden. Typ und Größe deshalb immer auf dem Server noch einmal prüfen. Die Prüfung im Client dient nur dem Komfort der Nutzer.
Dateinamen sind Benutzereingaben: file.name niemals ungeprüft per innerHTML einfügen (XSS-Gefahr). Stattdessen textContent verwenden. Auf dem Server den Namen nicht ungeprüft als Pfad nutzen (Path Traversal).
Speicherlecks: Adressen aus URL.createObjectURL(file) halten die Datei im Speicher, bis URL.revokeObjectURL() aufgerufen oder die Seite geschlossen wird.
Kein echter Pfad: Aus Datenschutzgründen gibt der Browser keinen vollständigen Dateipfad preis. webkitRelativePath ist nur bei <input webkitdirectory> gefüllt.
Nur lesbar: File-Objekte lassen sich nicht verändern. Um Dateien auf die Festplatte zu schreiben, braucht man die File System Access API (vor allem Chromium) oder einen Download-Link.
Große Dateien: text() und arrayBuffer() laden die ganze Datei in den Speicher. Bei mehreren hundert MB besser stream() oder slice() verwenden.
Kompatibilität: File und der Konstruktor funktionieren in allen modernen Browsern. Blob.prototype.text()/stream() gibt es seit etwa 2019/2020. In Node.js ist File ab Version 20 global verfügbar (vorher über node:buffer).

Siehe auch

Blob Blob.prototype.text() Fence HID Ink