FileSystemFileHandle.getFile() — Methode · JavaScript-Referenz

Signatur

FileSystemFileHandle.prototype.getFile()

Beschreibung

getFile() liefert zu einem FileSystemFileHandle ein File-Objekt mit dem Inhalt und den Metadaten (name, size, type, lastModified) zum Zeitpunkt des Aufrufs. Das Handle erhältst du z. B. über window.showOpenFilePicker(), per Drag & Drop mit DataTransferItem.getAsFileSystemHandle() oder aus dem Origin Private File System (OPFS) über navigator.storage.getDirectory().

Das zurückgegebene File ist ein Blob. Du kannst es also mit text(), arrayBuffer(), stream() oder slice() lesen, per URL.createObjectURL() anzeigen oder in einem FormData hochladen.

Wichtig: Das File ist eine Momentaufnahme. Ändert sich die Datei auf dem Datenträger danach (z. B. durch einen FileSystemWritableFileStream oder ein anderes Programm), können Lesezugriffe auf das alte File mit einem NotReadableError fehlschlagen. Willst du den aktuellen Stand lesen, rufst du getFile() einfach erneut auf.

Rückgabewert

Typ

Promise<File>

Beschreibung

Ein Promise, das mit einem File-Objekt erfüllt wird. Es wird abgelehnt mit NotAllowedError, wenn die Leseberechtigung nicht erteilt ist, und mit NotFoundError, wenn die Datei nicht mehr existiert.

Beispiele

Textdatei über den Datei-Dialog öffnen und lesen

const openTextFile = async () => {
  // Muss durch eine Nutzeraktion (z. B. Klick) ausgelöst werden
  const [handle] = await window.showOpenFilePicker({
    types: [{ description: 'Textdateien', accept: { 'text/plain': ['.txt', '.md'] } }]
  });
  const file = await handle.getFile();
  console.log(file.name, file.size, 'Bytes');
  const inhalt = await file.text();
  console.log(inhalt.slice(0, 100));
};

document.querySelector('#oeffnen').addEventListener('click', openTextFile);

notizen.txt 1342 Bytes # Meine Notizen ...

Datei im Origin Private File System (OPFS) schreiben und wieder lesen

const root = await navigator.storage.getDirectory();
const handle = await root.getFileHandle('config.json', { create: true });

const writable = await handle.createWritable();
await writable.write(JSON.stringify({ theme: 'dark' }));
await writable.close();

// Nach dem Schreiben ein NEUES File holen
const file = await handle.getFile();
const config = JSON.parse(await file.text());
console.log(config.theme, file.type || '(kein MIME-Typ)');

dark (kein MIME-Typ)

Auf Änderungen prüfen (Polling über lastModified)

const watchFile = (handle, onChange, intervall = 2000) => {
  let zuletzt = 0;
  return setInterval(async () => {
    try {
      const file = await handle.getFile();
      if (file.lastModified !== zuletzt) {
        zuletzt = file.lastModified;
        onChange(await file.text());
      }
    } catch (err) {
      console.error('Lesen fehlgeschlagen:', err.name);
    }
  }, intervall);
};

// Nutzung: const id = watchFile(handle, (text) => console.log('Neu:', text.length));

Bild aus Handle als Vorschau anzeigen

const showPreview = async (handle) => {
  const file = await handle.getFile();
  const url = URL.createObjectURL(file);
  const img = document.querySelector('#vorschau');
  img.onload = () => URL.revokeObjectURL(url); // Speicher freigeben
  img.src = url;
};

// Wichtig · Fallstricke

Kompatibilität: showOpenFilePicker() und damit Handles auf echte lokale Dateien gibt es nur in Chromium-Browsern (Chrome, Edge, Opera). Das OPFS (navigator.storage.getDirectory()) und damit getFile() funktioniert dagegen in allen modernen Browsern. Nur in sicheren Kontexten (HTTPS) verfügbar.
Momentaufnahme: Wird die Datei nach dem Aufruf verändert, wirft ein Lesezugriff auf das alte File einen NotReadableError. Nach jedem Schreibvorgang getFile() erneut aufrufen.
Berechtigungen: Handles, die in IndexedDB gespeichert wurden, verlieren in einer neuen Sitzung oft ihre Leseberechtigung. Vorher mit handle.queryPermission({ mode: 'read' }) prüfen und ggf. requestPermission() aufrufen (das braucht eine Nutzeraktion), sonst folgt ein NotAllowedError.
Das Promise wird mit NotFoundError abgelehnt, wenn die Datei inzwischen gelöscht oder verschoben wurde.
Im OPFS ist file.type meist leer, weil kein MIME-Typ gespeichert wird.
Für häufige, schnelle Lese- und Schreibzugriffe im OPFS ist createSyncAccessHandle() in einem Worker deutlich schneller als wiederholtes getFile().

Siehe auch

File Blob.text() FileSystemFileHandle.createWritable() FileSystemFileHandle.createSyncAccessHandle() FileSystemFileEntry.file()