Testowanie origin interfejsu File System Observer API

Thomas Steiner

Zarówno interfejs File System API, jak i interfejs Origin Private File System API umożliwiają deweloperom dostęp do plików i katalogów na urządzeniu użytkownika. Pierwsza z nich umożliwia programistom odczytywanie i zapisywanie danych w zwykłym, widocznym dla użytkownika systemie plików, a druga otwiera specjalny system plików, ukryty przed użytkownikiem, który jest prywatny dla źródła każdej witryny i zapewnia pewne korzyści związane ze zwiększeniem wydajności. W obu przypadkach sposób interakcji programistów z plikami i katalogami polega na używaniu obiektów FileSystemHandle, a konkretnie obiektów FileSystemFileHandle w przypadku plików i FileSystemDirectoryHandle w przypadku katalogów. Do tej pory informowanie o zmianach w pliku lub katalogu w którymkolwiek z systemów plików wymagało pewnej formy sondowania i porównywania sygnatury czasowej lastModified lub nawet zawartości pliku.

Interfejs File System Observer API, dostępny w testowaniu origin w Chrome 129, zmienia tę sytuację i umożliwia automatyczne powiadamianie deweloperów o zmianach. Z tego przewodnika dowiesz się, jak działa ta funkcja i jak z niej korzystać.

Przypadki użycia

Używaj interfejsu File System Observer API w aplikacjach, które muszą być informowane o możliwych zmianach w systemie plików, gdy tylko się pojawią.

  • internetowe zintegrowane środowiska programistyczne (IDE) przedstawiające drzewo systemu plików projektu;
  • Aplikacje synchronizujące zmiany w systemie plików z serwerem. Przykładem może być plik bazy danych SQLite.
  • Aplikacje, które muszą powiadamiać główny wątek o zmianach w systemie plików z poziomu instancji roboczej lub innej karty.
  • Aplikacje, które obserwują katalog zasobów, na przykład w celu automatycznej optymalizacji obrazów.
  • Funkcje, które korzystają z szybkiego wczytywania, np. prezentacje w formacie HTML, w których wczytywanie jest wywoływane przez zmianę pliku.

Jak korzystać z interfejsu File System Observer API

Wykrywanie cech

Aby sprawdzić, czy interfejs API File System Observer jest obsługiwany, uruchom test funkcji, jak w tym przykładzie.

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

Inicjowanie obserwatora systemu plików

Inicjalizacja obserwatora systemu plików przez wywołanie funkcji new FileSystemObserver(), podając jako argument funkcję callback.

const observer = new FileSystemObserver(callback);

Rozpoczynanie monitorowania pliku lub katalogu

Aby rozpocząć obserwowanie pliku lub katalogu, wywołaj asynchroniczną metodę observe() instancji FileSystemObserver. Jako argument podaj tej metodzie FileSystemHandle wybranego pliku lub katalogu. Podczas obserwowania katalogu dostępny jest opcjonalny argument options, który pozwala określić, czy chcesz otrzymywać informacje o zmianach w katalogu w sposób rekurencyjny (czyli w przypadku samego katalogu oraz wszystkich zawartych w nim podkatalogów i plików). Domyślnie jest to tylko katalog i pliki bezpośrednio w nim zawarte.

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

Wywołanie zwrotne

Gdy w systemie plików nastąpią zmiany, wywoływana jest funkcja z argumentami zmianą systemu plików records i samą strukturą observer. Argument observer możesz użyć na przykład do odłączenia obserwatora (patrz Zatrzymywanie obserwacji systemu plików), gdy interesujące Cię pliki zostaną usunięte.

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

Rekord zmiany w systemie plików

Każdy rekord zmiany w systemie plików ma taką strukturę. Wszystkie pola są tylko do odczytu.

  • root (a FileSystemHandle): uchwyt przekazany do funkcji FileSystemObserver.observe().
  • changedHandle (a FileSystemHandle): uchwyt, którego dotyczy zmiana w systemie plików. To pole będzie miało wartość null w przypadku zdarzeń typu "errored", "unknown" i "disappeared". Aby sprawdzić, który plik lub katalog zniknął, użyj relativePathComponents.
  • relativePathComponents (element Array): ścieżka changedHandle względem root.
  • type (a String): typ zmiany. Możliwe są te typy:
    • "appeared": plik lub katalog został utworzony lub przeniesiony do folderu root.
    • "disappeared": plik lub katalog został usunięty lub przeniesiony poza root.
    • "modified": plik lub katalog został zmodyfikowany.
    • "moved": plik lub katalog został przeniesiony w ramach root.
    • "unknown": oznacza, że nie zostało zarejestrowanych co najmniej 1 wydarzenia. W odpowiedzi na to deweloperzy powinni przeprowadzić ankietę w katalogu obserwowanych.
    • "errored": obserwacja jest już nieaktualna. W takim przypadku możesz zatrzymać obserwowanie systemu plików. Ta wartość zostanie również wysłana, gdy zostanie osiągnięty maksymalny limit obserwacji dla danego źródła. Ten limit zależy od systemu operacyjnego i nie jest znany z góry. W takim przypadku witryna może podjąć kolejną próbę, ale nie ma gwarancji, że system operacyjny zwolnił wystarczającą ilość zasobów. Innym przypadkiem, w którym ta wartość jest wysyłana, jest usunięcie lub przeniesienie obserwowanego identyfikatora (czyli elementu wyższego rzędu w obserwacji). W takim przypadku najpierw wysyłane jest zdarzenie "disappeared", a potem zdarzenie "errored", które wskazuje, że obserwacja nie jest już aktualna. Wreszcie to zdarzenie jest wysyłane, gdy usuniesz uprawnienia do katalogu lub uchwytu pliku.
  • relativePathMovedFrom (element Array, opcjonalnie): poprzednia lokalizacja przeniesionego uchwytu. Dostępne tylko wtedy, gdy type ma wartość "moved".

Przerywanie obserwowania pliku lub katalogu

Aby przestać obserwować FileSystemHandle, wywołaj metodę unobserve(), przekazując jej uchwyt jako argument.

observer.unobserve(fileHandle);

Zatrzymanie obserwacji systemu plików

Aby przestać obserwować system plików, odłącz instancję FileSystemObserver w ten sposób:

observer.disconnect();

Wypróbuj API

Aby przetestować interfejs API File System Observer lokalnie, ustaw flagę #file-system-observer w pliku about:flags. Aby przetestować interfejs API z udziałem prawdziwych użytkowników, zarejestruj się w ramach testowania origin i postępuj zgodnie z instrukcjami podanymi w przewodniku Testowanie origin w Chrome. Testowanie origin będzie trwało od wersji Chrome 129 (11 września 2024 r.) do wersji Chrome 134 (26 lutego 2025 r.).

Prezentacja

Interfejs File System Observer API możesz zobaczyć w działaniu w ramach wbudowanego demo. Sprawdź kod źródłowy lub zmodyfikuj kod demonstracyjny na Glitch. Podczas demonstracji aplikacja losowo tworzy, usuwa lub modyfikuje pliki w obserwowanym katalogu i rejestruje tę aktywność w górnej części okna. Następnie w dolnej części okna aplikacji rejestruje zmiany w miarę ich występowania. Jeśli czytasz ten artykuł w przeglądarce, która nie obsługuje interfejsu File System Observer API, zapoznaj się z zrzutem ekranu z demonstracją.

Prześlij opinię

Jeśli chcesz przekazać opinię na temat interfejsu API obserwatora systemu plików, dodaj komentarz do problemu 123 w repozytorium WHATWG/fs.

Podziękowania

Ten dokument został sprawdzony przez Daseul Lee, Nathan Memmott, Etienne Noël i Rachel Andrew.