FileSystemObserver.observe() — Methode · JavaScript-Referenz

Signatur

FileSystemObserver.prototype.observe(handle, options)

Beschreibung

Die Methode observe() meldet eine Datei oder ein Verzeichnis bei einem FileSystemObserver an. Ab dann ruft der Browser bei Änderungen die Callback-Funktion auf, die du dem Konstruktor übergeben hast. Er übergibt ihr ein Array von FileSystemChangeRecord-Objekten und den Beobachter selbst. Jeder Eintrag hat einen type ("appeared", "disappeared", "modified", "moved", "unknown" oder "errored"), das geänderte Handle (changedHandle), das beobachtete Wurzel-Handle (root) und den relativen Pfad (relativePathComponents).

Beobachten kannst du Handles aus dem Origin Private File System (OPFS, über navigator.storage.getDirectory()) und Handles, die der Nutzer über showOpenFilePicker() oder showDirectoryPicker() freigegeben hat. Das lohnt sich zum Beispiel für Editoren, die Änderungen durch andere Programme sofort anzeigen, für Synchronisation zwischen Tabs über das OPFS oder für die Live-Vorschau eines Projektordners.

Bei Verzeichnissen legt die Option recursive fest, ob nur direkte Einträge oder auch alle Unterverzeichnisse beobachtet werden. Die Methode gibt ein Promise zurück. Es wird erfüllt, sobald die Beobachtung aktiv ist, und abgelehnt, wenn das Handle ungültig ist oder die Berechtigung fehlt.

Parameter

Name	Typ	Default	Beschreibung
$handle Pflicht	FileSystemFileHandle \| FileSystemDirectoryHandle \| FileSystemSyncAccessHandle		Das Handle der Datei oder des Verzeichnisses, das beobachtet werden soll.
$options	object	{}	Optionales Konfigurationsobjekt.
$options.recursive	boolean	false	Nur für Verzeichnisse: Bei `true` werden auch Änderungen in allen Unterverzeichnissen gemeldet.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald die Beobachtung aktiv ist. Es wird z. B. mit NotFoundError oder NotAllowedError abgelehnt, wenn das Handle nicht existiert oder die Berechtigung fehlt.

Beispiele

OPFS-Verzeichnis rekursiv beobachten

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

const observer = new FileSystemObserver(callback);
const root = await navigator.storage.getDirectory();
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();

appeared: notizen.txt modified: notizen.txt

Vom Nutzer gewählte Datei im Editor live neu laden

const [handle] = await window.showOpenFilePicker();
const editor = document.querySelector('#editor');

const laden = async () => {
  const file = await handle.getFile();
  editor.value = await file.text();
};

const observer = new FileSystemObserver(async (records) => {
  if (records.some((r) => r.type === 'modified')) {
    await laden();
    console.log('Datei wurde extern geändert und neu geladen.');
  }
});

await laden();
await observer.observe(handle);

Datei wurde extern geändert und neu geladen.

Mit Feature-Erkennung und Fehlerbehandlung

const beobachte = async (handle) => {
  if (!('FileSystemObserver' in self)) {
    console.warn('FileSystemObserver wird nicht unterstützt – Fallback auf Polling.');
    return null;
  }
  const observer = new FileSystemObserver((records) => {
    for (const { type, changedHandle } of records) {
      if (type === 'errored') {
        console.error('Beobachtung fehlgeschlagen, wird beendet.');
        observer.disconnect();
        return;
      }
      console.log(type, changedHandle?.name);
    }
  });
  try {
    await observer.observe(handle, { recursive: false });
    return observer;
  } catch (err) {
    console.error(`observe() fehlgeschlagen: ${err.name}`);
    return null;
  }
};

const dir = await navigator.storage.getDirectory();
const observer = await beobachte(dir);
// Später aufräumen:
// observer?.unobserve(dir);

// Wichtig · Fallstricke

Experimentell und nicht standardisiert: Die API gibt es bisher nur in Chromium-Browsern (Chrome/Edge 133+, vorher als Origin Trial ab 129). Firefox und Safari unterstützen sie nicht. Prüfe deshalb immer mit 'FileSystemObserver' in self.
Nur in einem sicheren Kontext (HTTPS) verfügbar, im Fenster und in Web Workern.
Bei Dateien, die der Nutzer über einen Picker freigegeben hat, braucht es eine gültige Leseberechtigung. Fehlt sie, wird das Promise abgelehnt.
Der Typ "unknown" heißt, dass Ereignisse verloren gegangen sein können. Lies den Zustand dann komplett neu ein. "errored" heißt, dass die Beobachtung nicht mehr gültig ist.
Rufst du observe() mehrmals für dasselbe Handle auf, entsteht keine doppelte Beobachtung. Mit unobserve(handle) beendest du einzelne Beobachtungen, mit disconnect() alle.
Leistung: recursive: true auf großen Verzeichnisbäumen kann viel Systemaufwand und sehr viele Einträge erzeugen. Beobachte daher so gezielt wie möglich und bündle die Verarbeitung im Callback (Debouncing).
Wie oft und wie genau Änderungen gemeldet werden, hängt vom Betriebssystem ab. Die Reihenfolge und Zusammenfassung der Einträge ist nicht garantiert.

Siehe auch

FileSystemObserver.disconnect() PressureObserver.observe() ResizeObserver.observe() IntersectionObserver.observe() PressureObserver.unobserve()