Interfejs File System Access API 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 systemie plików widocznym dla użytkownika, a druga otwiera specjalny, ukryty przed użytkownikiem system plików, który jest prywatny dla źródła każdej witryny i ma pewne zalety związane z wydajnością. W obu przypadkach deweloperzy wchodzą w interakcję z plikami i katalogami za pomocą obiektów FileSystemHandle, a konkretnie FileSystemFileHandle w przypadku plików i FileSystemDirectoryHandle w przypadku katalogów. Do tej pory informowanie o zmianach w pliku lub katalogu w jednym z systemów plików wymagało pewnego rodzaju sondowania i porównywania lastModified sygnatury czasowej lub nawet samej zawartości pliku.
Interfejs File System Observer API, który jest testowany w Chrome 129, zmienia to i umożliwia automatyczne powiadamianie programistów o zmianach. Z tego przewodnika dowiesz się, jak działa ta funkcja i jak ją wypróbować.
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 od razu po ich wystąpieniu.
- Zintegrowane środowiska programistyczne (IDE) oparte na przeglądarce, które wyświetlają reprezentację drzewa systemu plików projektu.
- Aplikacje, które synchronizują zmiany w systemie plików z serwerem. Na przykład plik bazy danych SQLite.
- Aplikacje, które muszą powiadamiać wątek główny o zmianach w systemie plików z instancji roboczej lub innej karty.
- Aplikacje, które obserwują katalog zasobów, np. w celu automatycznej optymalizacji obrazów.
- Funkcje, które korzystają z szybkiego przeładowywania, np. prezentacje oparte na HTML, w których przeładowanie jest wywoływane przez zmianę pliku.
Jak korzystać z interfejsu File System Observer API
Wykrywanie cech
Aby sprawdzić, czy interfejs File System Observer API 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
Zainicjuj obserwatora systemu plików, wywołując funkcję new FileSystemObserver() i przekazując jej callback jako argument.
const observer = new FileSystemObserver(callback);
Rozpoczynanie obserwowania 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 możesz użyć opcjonalnego argumentu options, który pozwala określić, czy chcesz otrzymywać informacje o zmianach w katalogu rekursywnie (czyli w samym katalogu oraz wszystkich podkatalogach i plikach). Domyślnie monitorowany jest tylko sam katalog i bezpośrednio zawarte w nim pliki.
// Observe a file.
await observer.observe(fileHandle);
// Observe a directory.
await observer.observe(directoryHandle);
// Observe a directory recursively.
await observer.observe(directoryHandle, {recursive: true});
Funkcja wywołania zwrotnego
Gdy w systemie plików nastąpią zmiany, wywoływana jest funkcja zwrotna z zmianą w systemie plikówrecords i samym observer jako argumentami. Możesz użyć argumentu observer, aby na przykład odłączyć obserwatora (patrz Przestań obserwować system plików), gdy wszystkie interesujące Cię pliki zostaną usunięte.
const callback = (records, observer) => {
for (const record of records) {
console.log('Change detected', record);
}
};
Rekord zmian w systemie plików
Każdy rekord zmiany w systemie plików ma taką strukturę: Wszystkie pola są tylko do odczytu.
root(FileSystemHandle): uchwyt przekazany do funkcjiFileSystemObserver.observe().changedHandle(FileSystemHandle): uchwyt, którego dotyczy zmiana w systemie plików. W przypadku zdarzeń typu"errored","unknown"i"disappeared"to pole będzie miało wartośćnull. Aby sprawdzić, który plik lub katalog zniknął, użyj symbolurelativePathComponents.relativePathComponents(Array): ścieżkachangedHandlewzględemroot.type(aString): rodzaj zmiany. Dostępne są te typy:"appeared": plik lub katalog został utworzony lub przeniesiony do folderuroot."disappeared": plik lub katalog został usunięty lub przeniesiony zroot."modified": plik lub katalog został zmodyfikowany."moved": plik lub katalog został przeniesiony w ramachroot."unknown": oznacza to, że pominięto co najmniej 1 wydarzenie. Deweloperzy powinni w odpowiedzi na to zdarzenie sprawdzić obserwowany katalog."errored": obserwacja jest już nieważna. W takim przypadku możesz przestać obserwować system plików. Ta wartość zostanie też wysłana po osiągnięciu maksymalnego limitu obserwacji dla danej domeny. Ten limit zależy od systemu operacyjnego i nie jest znany z góry. W takiej sytuacji witryna może spróbować ponownie, ale nie ma gwarancji, że system operacyjny zwolnił wystarczającą ilość zasobów. Innym przypadkiem, w którym ta wartość zostanie wysłana, jest usunięcie lub przeniesienie obserwowanego uchwytu (czyli korzenia obserwacji). W tym przypadku najpierw wysyłane jest zdarzenie"disappeared", a potem zdarzenie"errored", co oznacza, że obserwacja nie jest już ważna. To zdarzenie jest wysyłane po usunięciu uprawnień do katalogu lub uchwytu pliku.
relativePathMovedFrom(Array, opcjonalny): poprzednia lokalizacja przeniesionego uchwytu. Dostępne tylko wtedy, gdytypema wartość"moved".
Zatrzymywanie obserwowania pliku lub katalogu
Aby przestać obserwować FileSystemHandle, wywołaj metodę unobserve(), przekazując jej uchwyt jako argument.
observer.unobserve(fileHandle);
Zatrzymywanie obserwowania 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 File System Observer API lokalnie, ustaw flagę #file-system-observer w pliku about:flags. Aby przetestować interfejs API z udziałem prawdziwych użytkowników, zarejestruj się w wersji próbnej origin i postępuj zgodnie z instrukcjami w przewodniku Wersje próbne origin w Chrome. Testowanie origin będzie prowadzone od Chrome 129 (11 września 2024 r.) do Chrome 134 (26 lutego 2025 r.).
Prezentacja
Interfejs File System Observer API możesz zobaczyć w działaniu w wbudowanej wersji demonstracyjnej. Sprawdź kod źródłowy. Wersja demonstracyjna losowo tworzy, usuwa lub modyfikuje pliki w obserwowanym katalogu i rejestruje swoją aktywność w górnej części okna aplikacji. Następnie rejestruje zmiany w dolnej części okna aplikacji. Jeśli czytasz ten artykuł w przeglądarce, która nie obsługuje interfejsu File System Observer API, zobacz zrzut ekranu wersji demonstracyjnej.
Prześlij opinię
Jeśli masz uwagi dotyczące kształtu interfejsu File System Observer API, skomentuj problem nr 123 w repozytorium WHATWG/fs.
Przydatne linki
- Wyjaśnienie
- Sprawdzenie przez TAG
- Stanowisko Mozilli w sprawie standardów
- Stanowisko WebKit w sprawie standardów
- ChromeStatus
- Błąd w Chromium
Podziękowania
Ten dokument został sprawdzony przez Daseul Lee, Nathana Memmotta, Etienne Noël i Rachel Andrew.