Ursprungstest der File System Observer API

Thomas Steiner

Sowohl die File System Access API als auch die Origin Private File System API ermöglichen es Entwicklern, auf Dateien und Verzeichnisse auf dem Gerät des Nutzers zuzugreifen. Mit ersterem können Entwickler im regulären, für Nutzer sichtbaren Dateisystem lesen und schreiben. Letzteres öffnet ein spezielles, für Nutzer ausgeblendetes Dateisystem, das nur für den Ursprung jeder Website zugänglich ist und bestimmte Leistungsvorteile bietet. In beiden Fällen interagieren Entwickler über FileSystemHandle-Objekte mit Dateien und Verzeichnissen, genauer gesagt FileSystemFileHandle für Dateien und FileSystemDirectoryHandle für Verzeichnisse. Bisher war es erforderlich, eine Art Abfrage durchzuführen und den lastModified-Zeitstempel oder sogar den Dateiinhalt selbst zu vergleichen, um über Änderungen an einer Datei oder einem Verzeichnis in einem der Dateisysteme informiert zu werden.

Die File System Observer API, die seit Chrome 129 im Ursprungstest verfügbar ist, ändert das und ermöglicht es Entwicklern, automatisch benachrichtigt zu werden, wenn Änderungen auftreten. In diesem Leitfaden wird erläutert, 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 Änderungen am Dateisystem informiert werden müssen.

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

Verwendung der File System Observer API

Funktionserkennung

Führen Sie einen Funktionstest 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-Beobachter initialisieren

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

const observer = new FileSystemObserver(callback);

Datei oder Verzeichnis beobachten

Wenn Sie eine Datei oder ein Verzeichnis beobachten möchten, rufen Sie die asynchrone observe()-Methode der FileSystemObserver-Instanz auf. Geben Sie dieser Methode den FileSystemHandle der ausgewählten Datei oder des ausgewählten Verzeichnisses als Argument an. Wenn Sie ein Verzeichnis beobachten, 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 darin direkt 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 auftreten, wird eine Callback-Funktion mit der Dateisystemänderung records und dem observer selbst als Argumenten aufgerufen. Mit dem observer-Argument können Sie beispielsweise die Verbindung des Beobachters trennen (siehe Beobachtung des Dateisystems beenden), wenn alle Dateien gelöscht wurden, die Sie beobachten möchten.

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

Der Dateisystemänderungsdatensatz

Jeder Dateisystemänderungsdatensatz hat die folgende Struktur. Alle Felder sind schreibgeschützt.

  • root (ein FileSystemHandle): Der an die Funktion FileSystemObserver.observe() übergebene Handle.
  • changedHandle (ein FileSystemHandle): Der Handle, der von der Dateisystemänderung betroffen ist. Dieses Feld hat den Wert null für Ereignisse vom Typ "errored", "unknown" und "disappeared". Verwenden Sie relativePathComponents, um zu sehen, welche Datei oder welches Verzeichnis verschwunden ist.
  • relativePathComponents (ein Array): Der Pfad der changedHandle relativ zur root.
  • type (ein String): Die Art der Änderung. Folgende Typen sind möglich:
    • "appeared": Die Datei oder das Verzeichnis wurde im root erstellt oder 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 des root verschoben.
    • "unknown": Dies bedeutet, dass null oder mehr Ereignisse verpasst wurden. Entwickler sollten daraufhin das beobachtete Verzeichnis abfragen.
    • "errored": Die Beobachtung ist nicht mehr gültig. In diesem Fall sollten Sie die Überwachung des Dateisystems beenden. Dieser Wert wird auch gesendet, wenn die maximale Anzahl der Beobachtungen pro Ursprung erreicht ist. Dieses Limit ist vom Betriebssystem abhängig und kann nicht im Voraus bestimmt werden. In diesem Fall kann die Website einen erneuten Versuch starten. Es gibt jedoch keine Garantie dafür, dass das Betriebssystem genügend Ressourcen freigegeben hat. Ein weiterer Fall, in dem dieser Wert gesendet wird, ist, wenn der beobachtete Handle (d. h. der Ursprung der Beobachtung) gelöscht oder verschoben wird. In diesem Fall wird zuerst das Ereignis "disappeared" gesendet, gefolgt von einem Ereignis "errored", das angibt, dass die Beobachtung nicht mehr gültig ist. Dieses Ereignis wird außerdem gesendet, wenn die Berechtigung für den Verzeichnis- oder Dateihandle entfernt wird.
  • relativePathMovedFrom (ein Array, optional): Der vorherige Standort eines verschobenen Ziehpunkts. Nur verfügbar, wenn der type "moved" ist.

Beobachtung einer Datei oder eines Verzeichnisses beenden

Wenn Sie die Beobachtung einer FileSystemHandle beenden möchten, rufen Sie die Methode unobserve() auf und übergeben Sie dabei den 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 so:

observer.disconnect();

API testen

Wenn Sie die File System Observer API lokal testen möchten, 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 Chrome-Ursprungstests. 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. Sehen Sie sich den Quellcode an oder remixen Sie den Democode auf Glitch. In der Demo werden Dateien in einem beobachteten Verzeichnis zufällig erstellt, gelöscht oder geändert. Die Aktivitäten werden im oberen Teil 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.