new FileSystemObserver() — Methode · JavaScript-Referenz

Signatur

new FileSystemObserver(callback)

Beschreibung

Der Konstruktor FileSystemObserver() legt einen Beobachter für die File System API an. Er funktioniert ähnlich wie MutationObserver oder ResizeObserver: Du übergibst eine Callback-Funktion. Sie wird aufgerufen, sobald sich in einer beobachteten Datei oder einem beobachteten Verzeichnis etwas ändert, also beim Anlegen, Löschen, Ändern oder Verschieben.

Die Beobachtung beginnt noch nicht mit dem Konstruktor, sondern erst mit observer.observe(handle, options). Als handle gehen ein FileSystemFileHandle, ein FileSystemDirectoryHandle oder ein FileSystemSyncAccessHandle. Beobachten lassen sich sowohl Handles aus dem Origin Private File System (OPFS, über navigator.storage.getDirectory()) als auch vom Nutzer gewählte Dateien, z. B. über showDirectoryPicker().

Typische Anwendungsfälle sind Web-IDEs, die ein Projektverzeichnis synchron halten, Fotoverwaltungen, die neue Bilder in einem Ordner erkennen, oder die Abstimmung zwischen mehreren Tabs bzw. Workern, die in dasselbe OPFS schreiben. So musst du Verzeichnisse nicht mehr regelmäßig manuell abfragen (Polling).

Die Callback-Funktion bekommt ein Array von FileSystemChangeRecord-Objekten. Jedes davon hat die Eigenschaften type ("appeared", "disappeared", "modified", "moved", "unknown", "errored"), changedHandle, root, relativePathComponents und bei Verschiebungen zusätzlich relativePathMovedFrom.

Parameter

Name	Typ	Default	Beschreibung
$callback Pflicht	(records: FileSystemChangeRecord[], observer: FileSystemObserver) => void		Wird bei erkannten Änderungen aufgerufen. Das erste Argument ist ein Array von `FileSystemChangeRecord`-Objekten, das zweite die Observer-Instanz selbst, z. B. um `disconnect()` aufzurufen.

Rückgabewert

Typ

FileSystemObserver

Beschreibung

Eine neue FileSystemObserver-Instanz mit den Methoden observe(), unobserve() und disconnect().

Beispiele

Observer anlegen und ein OPFS-Verzeichnis rekursiv beobachten

// Feature-Erkennung
if ('FileSystemObserver' in self) {
  const root = await navigator.storage.getDirectory();

  const observer = new FileSystemObserver((records) => {
    for (const record of records) {
      const pfad = record.relativePathComponents.join('/');
      console.log(`${record.type}: ${pfad}`);
    }
  });

  await observer.observe(root, { recursive: true });

  // Änderung auslösen
  const datei = await root.getFileHandle('notizen.txt', { create: true });
  const writable = await datei.createWritable();
  await writable.write('Hallo Welt');
  await writable.close();
} else {
  console.log('FileSystemObserver wird nicht unterstützt');
}

appeared: notizen.txt modified: notizen.txt

Vom Nutzer gewählten Projektordner synchron halten

const button = document.querySelector('#ordner-oeffnen');

button.addEventListener('click', async () => {
  const dirHandle = await window.showDirectoryPicker();

  const observer = new FileSystemObserver((records, obs) => {
    for (const { type, changedHandle, relativePathComponents, relativePathMovedFrom } of records) {
      switch (type) {
        case 'moved':
          console.log(`Verschoben: ${relativePathMovedFrom.join('/')} → ${relativePathComponents.join('/')}`);
          break;
        case 'errored':
          console.warn('Beobachtung fehlgeschlagen, wird beendet');
          obs.disconnect();
          break;
        case 'unknown':
          console.log('Änderungen möglicherweise verpasst – Verzeichnis neu einlesen');
          break;
        default:
          console.log(`${type}: ${changedHandle.name}`);
      }
    }
  });

  await observer.observe(dirHandle, { recursive: true });
});

modified: index.html Verschoben: alt.css → styles/neu.css

Einzelne Datei beobachten und Beobachtung wieder beenden

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

const observer = new FileSystemObserver(async (records) => {
  const file = await config.getFile();
  console.log('Neue Konfiguration:', await file.text());
});

await observer.observe(config);

// Später, z. B. beim Verlassen der Ansicht:
observer.unobserve(config); // nur dieses Handle
observer.disconnect();      // alle Beobachtungen beenden

Neue Konfiguration: {"theme":"dark"}

// Wichtig · Fallstricke

Experimentell und nicht standardisiert: Aktuell nur in Chromium-basierten Browsern verfügbar, anfangs hinter einem Origin Trial bzw. Flag. Firefox und Safari unterstützen die API nicht. Prüfe die Verfügbarkeit immer vorher mit 'FileSystemObserver' in self.
Der Konstruktor allein beobachtet noch nichts. Erst observe() startet die Beobachtung, und diese Methode gibt ein Promise zurück, das du mit await abwarten solltest.
Ohne callback oder mit einem Wert, der keine Funktion ist, wirft der Konstruktor einen TypeError.
Bei vielen schnellen Änderungen fasst der Browser Ereignisse zusammen oder meldet "unknown". Deine Anwendung sollte dann den Zustand vollständig neu einlesen, statt sich auf einzelne Änderungsmeldungen zu verlassen.
Bei vom Nutzer gewählten Dateien gelten die Berechtigungen der File System Access API. Wird die Leseberechtigung entzogen, erhältst du einen Eintrag vom Typ "errored".
Die API ist nur in sicheren Kontexten (HTTPS) verfügbar, im Fenster und in Workern. Rufe disconnect() auf, wenn du die Beobachtung nicht mehr brauchst, damit keine Ressourcen unnötig belegt bleiben.

Siehe auch

new PressureObserver() new ResizeObserver() new IntersectionObserver() new ReportingObserver() new MutationObserver()