File API - JavaScript lernen

File API in JavaScript: Mit Benutzerdateien interagieren

Die File API in JavaScript ist ein leistungsstarkes Werkzeug, das Webentwicklern ermöglicht, auf der Client-Seite mit Dateien zu interagieren — Benutzer können Dateien in Webanwendungen auswählen, lesen und bearbeiten. Diese API hat zahlreiche Anwendungsbereiche, darunter das Hochladen von Dateien, die Verarbeitung benutzergenerierter Inhalte und dateibezogene Operationen. In diesem Artikel erklären wir, was die File API ist, welche Vorteile sie bietet, wann man sie einsetzen sollte und welche typischen Anwendungsfälle es gibt.

Was ist die File API?

Die File API ist eine JavaScript-API, die Zugriff auf Dateien ermöglicht, die der Benutzer über Datei-Eingabefelder (<input type="file">) ausgewählt oder auf Webseiten gezogen hat. Sie stellt eine kleine Familie von Schnittstellen bereit, die zusammenarbeiten:

File — repräsentiert eine einzelne Datei, die der Benutzer ausgewählt hat. Sie enthält Metadaten wie name, size (in Bytes), type (MIME-Typ) und lastModified (ein Zeitstempel). Ein File-Objekt ist eine spezielle Art von Blob.
Blob — ein Block unveränderlicher Binärdaten ("Binary Large Object"). Jede File ist ein Blob, aber man kann auch eigene Blobs erstellen, um sie herunterzuladen oder hochzuladen. Weitere Informationen dazu gibt es im eigenen Kapitel JavaScript Blob.
FileList — die array-ähnliche Sammlung, die von input.files zurückgegeben wird. Man kann darauf mit [0] zugreifen oder sie iterieren.
FileReader — ein asynchroner Lesemechanismus, der den Inhalt einer Datei in den Speicher lädt — als Text, Data-URL oder ArrayBuffer.

Da dies alles im Browser abläuft, können Dateien vor jeder Serverinteraktion geprüft, validiert und in der Vorschau angezeigt werden.

Die File API liest nur Dateien, die der Benutzer explizit bereitstellt. Eine Seite kann niemals stillschweigend beliebige Dateien von der Festplatte des Besuchers öffnen — das ist eine bewusste Sicherheitsgrenze.

Lesemethoden im Überblick

FileReader bietet vier Lesemethoden. Wählen Sie diejenige aus, die dem gewünschten Ergebnis entspricht:

Methode	Ergebnistyp	Typische Verwendung
`readAsText(file)`	string	`.txt`, `.csv`, `.json`, Quellcode
`readAsDataURL(file)`	`data:`-URL-string	Bild-/Audio-/Video-Vorschau via `src`
`readAsArrayBuffer(file)`	`ArrayBuffer`	Binär-Parsing, Hashing, Byte-Analyse
`readAsBinaryString(file)`	string aus Bytes	veraltet; `readAsArrayBuffer` bevorzugen

Moderne Browser bieten auch promise-basierte Kurzformen direkt am Blob: await file.text(), await file.arrayBuffer() und file.stream(). Diese ersetzen FileReader in neuem Code häufig und lassen sich gut mit async/await kombinieren.

Wann sollte man die File API verwenden?

Die File API ist besonders nützlich, wenn man:

Datei-Uploads verwalten möchte — Benutzer sollen Dateien von ihren Geräten auswählen und senden können.
Dateien als Vorschau anzeigen möchte — ein Miniaturbild eines ausgewählten Bildes oder den Text eines Dokuments anzeigen, bevor es hochgeladen wird.
Client-seitig validieren möchte — einen falschen MIME-Typ oder eine zu große Datei ablehnen, bevor Bandbreite für einen Upload verbraucht wird.
Dateien lokal bearbeiten möchte — Bilder zuschneiden, Text bearbeiten oder CSV-Dateien verarbeiten, ohne einen Server-Roundtrip zu benötigen.

Für PDFs gilt ein Hinweis: Die File API erzeugt keine PDFs. Sie wählt, liest und speichert Dateien nur. Um ein PDF zu erstellen, wird eine Bibliothek wie jsPDF benötigt; die File API (über einen Blob) kann dann den Download auslösen.

Einfaches Beispiel: Dateiinhalt lesen

Hier ist ein einfaches Beispiel, das die File API in JavaScript verwendet, um eine vom Benutzer ausgewählte Textdatei zu lesen und deren Inhalt anzuzeigen. Dieses Demo hilft dabei zu verstehen, wie man mit Web-Technologien mit Dateien auf dem eigenen Gerät interagiert.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>File Reader Example</title>
  </head>
  <body>
    <h1>Read Text File</h1>
    <p>First, choose a text file, then click the 'Read File' button to see your file's contents.</p>
    <input type="file" id="fileInput" accept=".txt" />
    <button onclick="readFile()">Read File</button>
    <pre id="fileContents"></pre>

    <script>
      function readFile() {
        const fileInput = document.getElementById("fileInput");
        const file = fileInput.files[0]; // Get the first file selected by the user

        if (file) {
          const reader = new FileReader();

          reader.onload = function (e) {
            const contents = e.target.result;
            document.getElementById("fileContents").textContent = contents;
          };

          reader.onerror = function (e) {
            console.error("Error reading file:", e.target.error.message);
          };

          reader.readAsText(file); // Read the file as text
        } else {
          alert("Please select a file.");
        }
      }
    </script>
  </body>
</html>

Probier es selbst »

In diesem Code:

Dateiauswahl: Der Benutzer wählt eine Textdatei (eine Datei mit der Erweiterung .txt) über das Datei-Eingabeelement aus.
Datei lesen: Wenn der Benutzer auf den "Read File"-Button klickt, wird die ausgewählte Datei als Text gelesen. Beachten Sie, dass FileReader-Operationen asynchron sind; der onload-Callback wird erst ausgeführt, nachdem die Datei vollständig gelesen wurde.
Datei anzeigen: Der Inhalt der Datei wird in einem <pre>-Element angezeigt, wobei die Formatierung der Textdatei erhalten bleibt.

Dieses Beispiel demonstriert auf einfache Weise die Fähigkeit der File API, mit vom Benutzer ausgewählten Dateien in einer Webanwendung zu lesen und zu interagieren.

Datei-Metadaten auslesen

Oft werden die Details einer Datei benötigt, bevor irgendetwas anderes getan wird — um sie zu validieren oder dem Benutzer zu zeigen, was er ausgewählt hat. Jedes File-Objekt stellt diese Metadaten synchron bereit, ohne dass ein Lesevorgang erforderlich ist:

const file = fileInput.files[0];

console.log(file.name);          // e.g. "report.pdf"
console.log(file.type);          // MIME type, e.g. "application/pdf"
console.log(file.size);          // size in bytes, e.g. 12048
console.log(file.lastModified);  // ms since the Unix epoch

Eine häufige Aufgabe ist es, die Byte-Anzahl in eine menschenlesbare Form umzuwandeln:

function formatBytes(bytes) {
  if (bytes === 0) return "0 B";
  const units = ["B", "KB", "MB", "GB"];
  const i = Math.floor(Math.log(bytes) / Math.log(1024));
  return (bytes / Math.pow(1024, i)).toFixed(1) + " " + units[i];
}

console.log(formatBytes(0));        // "0 B"
console.log(formatBytes(900));      // "900.0 B"
console.log(formatBytes(2048));     // "2.0 KB"
console.log(formatBytes(5242880));  // "5.0 MB"

Dateien vor dem Upload validieren

Client-seitige Validierung gibt dem Benutzer sofortiges Feedback und vermeidet unnötige Uploads. Die Validierung sollte immer auch auf dem Server wiederholt werden — Client-seitige Prüfungen sind eine Benutzerhilfe, keine Sicherheitsgarantie, da sie umgangen werden können.

function validateImage(file) {
  const allowedTypes = ["image/png", "image/jpeg", "image/webp"];
  const maxSize = 2 * 1024 * 1024; // 2 MB

  if (!allowedTypes.includes(file.type)) {
    return "Only PNG, JPEG, or WebP images are allowed.";
  }
  if (file.size > maxSize) {
    return "File is too large (max 2 MB).";
  }
  return null; // null means "valid"
}

// Simulate two checks:
console.log(validateImage({ type: "image/gif", size: 1000 }));
// "Only PNG, JPEG, or WebP images are allowed."
console.log(validateImage({ type: "image/png", size: 500 }));
// null

Bild-Vorschau vor dem Upload

Um ein Miniaturbild eines ausgewählten Bildes anzuzeigen, wird es als Data-URL gelesen und dieser string dem src-Attribut eines <img>-Elements zugewiesen. Der Browser dekodiert die Base64-Nutzlast direkt — ohne Server-Beteiligung.

<input type="file" id="imageInput" accept="image/*" />
<img id="preview" alt="Preview" width="200" />

<script>
  const input = document.getElementById("imageInput");
  const preview = document.getElementById("preview");

  input.addEventListener("change", () => {
    const file = input.files[0];
    if (!file) return;

    const reader = new FileReader();
    reader.onload = (e) => {
      preview.src = e.target.result; // a "data:image/...;base64,..." URL
    };
    reader.readAsDataURL(file);
  });
</script>

Bei großen Mediendateien sollte URL.createObjectURL(file) statt einer Data-URL bevorzugt werden — es gibt eine kurze blob:-Referenz zurück, ohne die gesamte Datei in einen string zu kopieren. Denken Sie daran, URL.revokeObjectURL() aufzurufen, wenn die Vorschau nicht mehr benötigt wird, damit der Browser den Speicher freigeben kann.

Datei mit modernen Promises lesen

In aktuellen Browsern kann FileReader vollständig übersprungen werden, indem die eigenen Methoden des Blobs mit await verwendet werden. Das ist übersichtlicher, wenn man sich bereits in einer async-Funktion befindet:

async function readTextFile(file) {
  const text = await file.text();
  return text.trim().split("\n").length; // count of lines
}

// Simulate a File with the same API as the real Blob:
const fakeFile = new Blob(["line 1\nline 2\nline 3"]);
readTextFile(fakeFile).then((lines) => console.log(lines)); // 3

Datei auf einen Server hochladen

Sobald eine Datei ausgewählt wurde, kann sie mit fetch und einem FormData-Body gesendet werden. Der Browser setzt die korrekten multipart/form-data-Header automatisch — Content-Type darf nicht manuell gesetzt werden:

async function uploadFile(file) {
  const formData = new FormData();
  formData.append("upload", file, file.name);

  const response = await fetch("/api/upload", {
    method: "POST",
    body: formData,
  });
  return response.ok;
}

Weitere Informationen zum vollständigen Anfrage-/Antwortmodell finden Sie im Kapitel Fetch API.

Häufige Fallstricke

FileReader ist asynchron. Das Ergebnis ist nur innerhalb von onload verfügbar; das Lesen von reader.result in der nächsten Zeile gibt null zurück.
input.files kann mehrere Dateien enthalten. Das multiple-Attribut zum Input hinzufügen und die FileList iterieren; andernfalls ist immer nur files[0] zugänglich.
Der value wird beim Abbrechen in einigen Browsern geleert. Die erneute Auswahl derselben Datei löst möglicherweise kein change-Event aus; zuerst input.value = "" zurücksetzen, wenn dies erkannt werden soll.
file.type kann leer sein. Bei unbekannten Erweiterungen kann der MIME-Typ "" sein; darauf sollte man sich nie als einzige Prüfung verlassen.
Object-URLs verursachen Speicherlecks. Jedem URL.createObjectURL() muss ein entsprechendes URL.revokeObjectURL() folgen.

Fazit

Die File API in JavaScript ermöglicht Webentwicklern, direkt in Webanwendungen mit Benutzerdateien zu arbeiten, und eröffnet damit Möglichkeiten zur Verbesserung von Benutzerinteraktionen und zur Bereitstellung einer nahtlosen Benutzererfahrung. Ob ein Datei-Upload, ein Dokumenten-Editor oder eine andere Anwendung, die Dateiverarbeitung erfordert — die File API stellt die Werkzeuge bereit, um funktionsreiche, client-seitige Dateiverarbeitungslösungen zu erstellen.

Für einen tieferen Einstieg empfehlen sich das Kapitel JavaScript Blob zum Erstellen und Herunterladen eigener Binärdaten, Drag and Drop mit JavaScript zum Ermöglichen des Datei-Drops auf die Seite sowie die Fetch API zum Senden von Dateien an einen Server.

Practice

Übung

Was kann man mit der File API in JavaScript tun?

Textdateien ladenEin Spiel spielenEine Bildergalerie erstellenEine Pizza bestellenEine Live-Vorschau von Bilddateien erzeugen