Ursprungstest der File System Observer API

Thomas Steiner

Mit der File System Access API und der Origin Private File System API können Entwickler auf Dateien und Verzeichnisse auf dem Gerät des Nutzers zugreifen. Mit der ersten Option können Entwickler das reguläre, für Nutzer sichtbare Dateisystem lesen und in dieses schreiben. Mit der zweiten Option wird ein spezielles, für Nutzer verborgenes Dateisystem geöffnet, das für den Ursprung jeder Website privat ist und bestimmte Leistungsvorteile bietet. Entwickler interagieren in beiden Fällen über FileSystemHandle-Objekte mit Dateien und Verzeichnissen, genauer gesagt über FileSystemFileHandle für Dateien und FileSystemDirectoryHandle für Verzeichnisse. Bisher war es erforderlich, Änderungen an einer Datei oder einem Verzeichnis in einem der beiden Dateisysteme durch Polling und Vergleichen des lastModified-Zeitstempels oder sogar des Dateiinhalts selbst zu ermitteln.

Die File System Observer API, die ab Chrome 129 als Ursprungstest verfügbar ist, ändert das und ermöglicht es Entwicklern, automatisch benachrichtigt zu werden, wenn Änderungen vorgenommen werden. In dieser Anleitung wird die Funktionsweise der Funktion erläutert und beschrieben, wie Sie sie ausprobieren können.

Anwendungsfälle

Verwenden Sie die File System Observer API in Apps, die über mögliche Änderungen am Dateisystem informiert werden müssen, sobald sie eintreten.

  • Webbasierte integrierte Entwicklungsumgebungen (IDEs), die eine Darstellung des Dateisystembaums eines Projekts zeigen.
  • Apps, die Änderungen am Dateisystem mit einem Server synchronisieren. Beispiel: eine SQLite-Datenbankdatei.
  • Apps, die den Hauptthread über Änderungen am Dateisystem von einem Worker oder einem anderen Tab aus benachrichtigen müssen.
  • Apps, die ein Ressourcenverzeichnis überwachen, um beispielsweise Bilder automatisch zu optimieren.
  • Anwendungen, die von Hot Reload profitieren, z. B. HTML-basierte Präsentationen, bei denen ein Reload durch eine Dateiänderung ausgelöst wird.

File System Observer API verwenden

Funktionserkennung

Führen Sie einen Feature-Test wie im folgenden Beispiel aus, um zu prüfen, ob die File System Observer API unterstützt wird.

if ('FileSystemObserver' in self) {
  // The File System Observer API is supported.
}

Dateisystem-Observer initialisieren

Initialisieren Sie einen File System Observer, indem Sie new FileSystemObserver() aufrufen und ihm eine callback-Funktion als Argument übergeben.

const observer = new FileSystemObserver(callback);

Beobachtung einer Datei oder eines Verzeichnisses starten

Rufen Sie zum Beobachten einer Datei oder eines Verzeichnisses die asynchrone Methode observe() der FileSystemObserver-Instanz auf. Geben Sie die FileSystemHandle der ausgewählten Datei oder des ausgewählten Verzeichnisses als Argument für diese Methode an. Beim Beobachten eines Verzeichnisses gibt es ein optionales options-Argument, mit dem Sie festlegen können, ob Sie rekursiv über Änderungen am Verzeichnis informiert werden möchten (d. h. für das Verzeichnis selbst und alle enthaltenen Unterverzeichnisse und Dateien). Standardmäßig wird nur das Verzeichnis selbst und die direkt darin enthaltenen Dateien beobachtet.

// Observe a file.
await observer.observe(fileHandle);
// Observe a directory.
await observer.observe(directoryHandle);
// Observe a directory recursively.
await observer.observe(directoryHandle, {recursive: true});

Die Callback-Funktion

Wenn Änderungen am Dateisystem vorgenommen werden, wird eine Callback-Funktion mit der Dateisystemänderung records und dem observer selbst als Argumente aufgerufen. Mit dem observer-Argument können Sie beispielsweise die Verbindung zum Observer trennen (siehe Dateisystem nicht mehr beobachten), wenn alle Dateien, die Sie interessieren, gelöscht wurden.

const callback = (records, observer) => {
  for (const record of records) {
    console.log('Change detected', record);
  }
};

Der Datensatz für Dateisystemänderungen

Jeder Datensatz für Änderungen am Dateisystem hat die folgende Struktur. Alle Felder sind schreibgeschützt.

  • root (ein FileSystemHandle): Das Handle, das an die Funktion FileSystemObserver.observe() übergeben wurde.
  • changedHandle (ein FileSystemHandle): Das Handle, das von der Änderung des Dateisystems betroffen ist. Dieses Feld ist null für Ereignisse vom Typ "errored", "unknown" und "disappeared". Verwenden Sie relativePathComponents, um herauszufinden, welche Datei oder welches Verzeichnis verschwunden ist.
  • relativePathComponents (ein Array): Der Pfad des changedHandle relativ zum root.
  • type (ein String): Die Art der Änderung. Folgende Typen sind möglich:
    • "appeared": Die Datei oder das Verzeichnis wurde erstellt oder in root verschoben.
    • "disappeared": Die Datei oder das Verzeichnis wurde gelöscht oder aus dem root verschoben.
    • "modified": Die Datei oder das Verzeichnis wurde geändert.
    • "moved": Die Datei oder das Verzeichnis wurde in root verschoben.
    • "unknown": Gibt an, dass null oder mehr Ereignisse nicht erfasst wurden. Entwickler sollten das überwachte Verzeichnis daraufhin abfragen.
    • "errored": Die Beobachtung ist nicht mehr gültig. In diesem Fall sollten Sie das Beobachten des Dateisystems beenden. Dieser Wert wird auch gesendet, wenn das maximale Limit für Beobachtungen pro Herkunft erreicht ist. Dieses Limit hängt vom Betriebssystem ab und ist nicht im Voraus bekannt. In diesem Fall kann die Website versuchen, den Vorgang noch einmal auszuführen. Es gibt jedoch keine Garantie dafür, dass das Betriebssystem genügend Ressourcen freigegeben hat. Dieser Wert wird auch gesendet, wenn das beobachtete Handle (der Stamm der Beobachtung) gelöscht oder verschoben wird. In diesem Fall wird zuerst das "disappeared"-Ereignis und dann das "errored"-Ereignis gesendet, um anzugeben, dass die Beobachtung nicht mehr gültig ist. Schließlich wird dieses Ereignis gesendet, wenn die Berechtigung für das Verzeichnis oder den Dateihandle entfernt wird.
  • relativePathMovedFrom (Array, optional): Der frühere Speicherort eines verschobenen Handles. Nur verfügbar, wenn der type "moved" ist.

Überwachung einer Datei oder eines Verzeichnisses beenden

Wenn Sie eine FileSystemHandle nicht mehr beobachten möchten, rufen Sie die Methode unobserve() auf und übergeben Sie das Handle als Argument.

observer.unobserve(fileHandle);

Beobachtung des Dateisystems beenden

Wenn Sie die Beobachtung des Dateisystems beenden möchten, trennen Sie die Verbindung zur FileSystemObserver-Instanz wie folgt.

observer.disconnect();

API testen

Wenn Sie die File System Observer API lokal testen möchten, legen Sie das Flag #file-system-observer in about:flags fest. Wenn Sie die API mit echten Nutzern testen möchten, registrieren Sie sich für den Ursprungstest und folgen Sie der Anleitung im Leitfaden Chrome-Ursprungstests. Der Ursprungstest läuft von Chrome 129 (11. September 2024) bis Chrome 134 (26. Februar 2025).

Demo

Die File System Observer API in Aktion sehen Sie in der eingebetteten Demo. Quellcode In der Demo werden Dateien in einem überwachten Verzeichnis zufällig erstellt, gelöscht oder geändert. Die Aktivitäten werden im oberen Bereich des App-Fensters protokolliert. Die Änderungen werden dann im unteren Bereich des App-Fensters protokolliert. Wenn Sie diese Seite in einem Browser aufrufen, der die File System Observer API nicht unterstützt, sehen Sie sich einen Screenshot der Demo an.

Feedback

Wenn Sie Feedback zur Form der File System Observer API haben, kommentieren Sie Issue #123 im WHATWG/fs-Repository.

Danksagungen

Dieses Dokument wurde von Daseul Lee, Nathan Memmott, Etienne Noël und Rachel Andrew geprüft.