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 Ersteren können Entwickler im regulären, für den Nutzer sichtbaren Dateisystem lesen und schreiben. Letzteres öffnet ein spezielles, vor dem Nutzerdateisystem verborgenes Geheimnis, das dem Ursprung der einzelnen Websites vorbehalten ist und gewisse Leistungsvorteile bietet. Entwickler interagieren in beiden Fällen über FileSystemHandle-Objekte, genauer gesagt, FileSystemFileHandle für Dateien und FileSystemDirectoryHandle für Verzeichnisse. Bisher musste der lastModified-Zeitstempel oder sogar der Dateiinhalt selbst abgefragt und verglichen werden, um über Änderungen an einer Datei oder einem Verzeichnis in einem der Dateisysteme informiert zu werden.

Mit der File System Observer API, die sich im Ursprungstest von Chrome 129 befindet, ändert sich dies und Entwickler können automatisch benachrichtigt werden, wenn Änderungen auftreten. In diesem Leitfaden erfahren Sie, wie die Funktion funktioniert und wie Sie sie ausprobieren können.

Anwendungsfälle

Verwenden Sie die File System Observer API in Apps, die sofort über mögliche Dateisystemänderungen informiert werden müssen.

• Webbasierte integrierte Entwicklungsumgebungen (Integrated Development Environment, IDEs), in denen die Dateisystemstruktur eines Projekts dargestellt wird.
• Apps, die Änderungen am Dateisystem mit einem Server synchronisieren Beispiel: eine SQLite-Datenbankdatei.
• Apps, die den Hauptthread über Änderungen des Dateisystems von einem Worker oder einem anderen Tab benachrichtigen müssen.
• Anwendungen, die ein Verzeichnis mit Ressourcen beobachten, um beispielsweise Bilder automatisch zu optimieren

File System Observer API verwenden

Funktionserkennung

Führen Sie einen Funktionstest wie im folgenden Beispiel durch, um herauszufinden, ob die File System Observer API unterstützt wird.

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

Hinweis: In der Erläuterung finden Sie allgemeine Ansätze zur Polyfill-Funktion für das Verhalten der File System Observer API durch Abfragen.

Dateisystembeobachter initialisieren

Initialisieren Sie einen Dateisystembeobachter, indem Sie new FileSystemObserver() aufrufen und eine callback-Funktion als Argument angeben.

const observer = new FileSystemObserver(callback);

Beginnen Sie mit der Beobachtung einer Datei oder eines Verzeichnisses

Rufen Sie die asynchrone observe()-Methode der FileSystemObserver-Instanz auf, um eine Datei oder ein Verzeichnis zu beobachten. Geben Sie für diese Methode den FileSystemHandle der ausgewählten Datei oder des ausgewählten Verzeichnisses als Argument an. Bei der Beobachtung eines Verzeichnisses gibt es ein optionales options-Argument, mit dem Sie auswählen 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. Die Standardoption besteht darin, nur das Verzeichnis selbst und die direkt enthaltenen Dateien zu beobachten.

// 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

Bei Änderungen am Dateisystem wird eine Callback-Funktion mit der Dateisystemänderung records und dem observer selbst als Argumente aufgerufen. Mit dem Argument observer können Sie beispielsweise die Verbindung zum Beobachter trennen (siehe Beobachtung des Dateisystems beenden), wenn alle Dateien gelöscht sind, die Sie interessieren.

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

Der Änderungseintrag des Dateisystems

Jeder Änderungseintrag im Dateisystem hat die folgende Struktur. Alle Felder sind schreibgeschützt.

• root (ein FileSystemHandle): Das an die Funktion FileSystemObserver.observe() übergebene Handle.
• changedHandle (ein FileSystemHandle): Der von der Änderung des Dateisystems betroffene Handle.
• relativePathComponents (Array): Der Pfad von changedHandle relativ zum root.
• type (ein String): Die Art der Änderung. Folgende Typen sind möglich: <ph type="x-smartling-placeholder">
  </ph>
  • "appeared": Die Datei oder das Verzeichnis wurde erstellt oder in den 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 innerhalb von root verschoben.
  • "unknown": Dies bedeutet, dass null oder mehr Ereignisse verpasst wurden. Entwickler sollten darauf reagieren, indem sie das überwachte Verzeichnis abfragen.
  • "errored": Die Beobachtung ist nicht mehr gültig. In diesem Fall sollten Sie die Beobachtung des Dateisystems beenden.
• relativePathMovedFrom (Array, optional): Der frühere Speicherort eines verschobenen Alias. Nur verfügbar, wenn „type“ den Wert „"moved"“ hat.

Hinweis: Je nach Betriebssystem werden möglicherweise nicht alle Änderungsereignisse mit derselben Detailebene gemeldet, z. B. wenn sich der Inhalt eines Verzeichnisses rekursiv ändert. Im besten Fall erhält die Website einen detaillierten Änderungseintrag mit der Art der Änderung und einem Handle für den betroffenen Pfad. Im schlimmsten Fall erhält die Website einen allgemeineren Änderungseintrag (d. h. einen type mit dem Wert "unknown"), der trotzdem noch das Verzeichnis auflistet, um herauszufinden, welches untergeordnete Element sich geändert hat. Dies stellt immer noch eine Verbesserung gegenüber Abfragen dar, da die Verzeichnisauflistung bei Bedarf von der Callback-Funktion gestartet werden kann, anstatt Änderungen in Intervallen abzufragen.

Hinweis: Unter Windows werden "moved"-Ereignisse zwischen Verzeichnissen nicht unterstützt. Sie werden als "disappeared" aus dem Quellverzeichnis und als "appeared" im Zielverzeichnis gemeldet. Sie werden als "moved" gemeldet, wenn sich Quelle und Ziel im selben Verzeichnis befinden.

Datei oder Verzeichnis nicht mehr beobachten

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

observer.unobserve(fileHandle);

Hinweis: Während des Ursprungstests wird die Methode unobserve() nicht unterstützt. Verwenden Sie als Behelfslösung die Methode disconnect().

Beobachtung des Dateisystems beenden

Wenn Sie das Dateisystem nicht mehr beobachten möchten, trennen Sie die Verbindung zur FileSystemObserver-Instanz:

observer.disconnect();

API testen

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

Demo

In der eingebetteten Demo können Sie die File System Observer API in Aktion sehen. Sieh dir den Quellcode an oder erstelle einen Remix des Democodes auf Glitch. Die Demo erstellt, löscht oder ändert nach dem Zufallsprinzip Dateien in einem beobachteten Verzeichnis und protokolliert seine Aktivität im oberen Teil des App-Fensters. Die Änderungen werden dann protokolliert, sobald sie im unteren Teil des App-Fensters auftreten. Wenn Sie dies in einem Browser lesen, 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 Problem Nr. 123 im WHATWG/fs-Repository.

Relevante Links

• Erklärung
• TAG-Überprüfung
• Position von Mozilla-Standards
• Position von WebKit-Standards
• ChromeStatus
• Chromium-Fehler

Danksagungen

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