Interfejs File System Access API i Origin Private File System API umożliwiają deweloperom dostęp do plików i katalogów na urządzeniu użytkownika. Pierwszy z nich umożliwia programistom odczytywanie i zapisywanie danych w zwykłym, widocznym dla użytkowników systemie plików. Drugi pozwala otworzyć specjalny, ukryty w systemie plików użytkownika plik, który jest prywatny dla źródła każdej witryny i ma pewne korzyści w zakresie wydajności. Sposób, w jaki programiści korzystają z plików i katalogów w obu przypadkach, to obiekty FileSystemHandle, a dokładniej FileSystemFileHandle w przypadku plików i FileSystemDirectoryHandle dla katalogów. Do tej pory informowanie o zmianach w pliku lub katalogu w jednym z tych systemów wymagało odpytywania i porównywania sygnatury czasowej lastModified lub nawet zawartości pliku.
Interfejs File System Observer API w ramach testowania origin Chrome 129 wprowadza zmiany i pozwala deweloperom otrzymywać automatyczne alerty 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, w których przypadku musisz od razu otrzymywać powiadomienia o możliwych zmianach w systemie plików.
- Internetowe zintegrowane środowiska programistyczne (IDE) przedstawiające drzewo systemu plików projektu.
- Aplikacje, które synchronizują zmiany w systemie plików z serwerem. Może to być na przykład plik bazy danych SQLite.
- Aplikacje, które muszą powiadamiać główny wątek systemu plików o zmianach z instancji roboczej lub innej karty.
- Aplikacje, które obserwują katalog zasobów, np. w celu automatycznego optymalizowania obrazów.
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 przykładzie poniżej.
if ('FileSystemObserver' in self) {
// The File System Observer API is supported.
}
Inicjowanie obserwatora systemu plików
Zainicjuj obserwator systemu plików, wywołując funkcję new FileSystemObserver() i podając jej funkcję callback jako argument.
const observer = new FileSystemObserver(callback);
Zacznij obserwować plik lub katalog
Aby rozpocząć obserwację pliku lub katalogu, wywołaj asynchroniczną metodę observe() instancji FileSystemObserver. Podaj tej metody jako argument FileSystemHandle wybranego pliku lub katalogu. Podczas obserwacji katalogu dostępny jest opcjonalny argument options, który pozwala określić, czy chcesz otrzymywać informacje o zmianach w katalogu rekurencyjnie (tzn. dotyczące samego katalogu oraz wszystkich zawartych w nim podkatalogów i plików). Domyślnym ustawieniem jest obserwowanie tylko katalogu i zawartych w nim plików.
// 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
Po wprowadzeniu zmian w systemie plików wywoływana jest funkcja wywołania zwrotnego z zmianą w systemie plików records i argumentem observer. Argumentu observer możesz użyć na przykład do odłączenia obserwatora (patrz Zatrzymaj obserwację systemu 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 zmian w systemie plików ma następującą strukturę. Wszystkie pola są tylko do odczytu.
root(FileSystemHandle): nick przekazywany do funkcjiFileSystemObserver.observe().changedHandle(aFileSystemHandle): nick, którego dotyczy zmiana w systemie plików.relativePathComponents(Array): ścieżka obiektuchangedHandlew odniesieniu doroot.type(aString): typ zmiany. Możliwe typy to:"appeared": plik lub katalog został utworzony albo przeniesiony do folderuroot."disappeared": plik lub katalog został usunięty albo przeniesiony zroot."modified": plik lub katalog został zmodyfikowany."moved": plik lub katalog został przeniesiony w folderzeroot."unknown": wskazuje, że pominięto co najmniej 0 wydarzeń. W odpowiedzi deweloperzy powinni w odpowiedzi na nie przeprowadzić ankiety w katalogu monitorowanych."errored": obserwacja straciła ważność. W takiej sytuacji możesz przestać obserwować system plików.
relativePathMovedFrom(Array, opcjonalnie): poprzednia lokalizacja przeniesionego nicka. Dostępne tylko wtedy, gdytypema wartość"moved".
Zatrzymywanie obserwowania pliku lub katalogu
Aby przestać obserwować właściwość FileSystemHandle, wywołaj metodę unobserve(), przekazując jej nick jako argument.
observer.unobserve(fileHandle);
Przerywanie obserwowania systemu plików
Aby przestać obserwować system plików, odłącz instancję FileSystemObserver w następujący sposób.
observer.disconnect();
Wypróbuj API
Aby przetestować lokalnie interfejs File System Observer API, ustaw flagę #file-system-observer w about:flags. Aby przetestować interfejs API na rzeczywistych użytkownikach, zarejestruj się w okresie próbnym origin i postępuj zgodnie z instrukcjami podanymi w przewodniku na temat testów origin Chrome. Okres próbny origin będzie obowiązywać od Chrome 129 (11 września 2024 r.) do Chrome 134 (26 lutego 2025 r.).
Prezentacja
Działanie interfejsu File System Observer API możesz zobaczyć w umieszczonej wersji demonstracyjnej. Sprawdź kod źródłowy lub zremiksuj kod demonstracyjny w usłudze Glitch. Wersja demonstracyjna losowo tworzy, usuwa lub modyfikuje pliki w obserwowanym katalogu i rejestruje jego aktywność w górnej części okna aplikacji. Następnie aplikacja rejestruje zmiany w miarę ich wprowadzania w dolnej części okna aplikacji. Jeśli używasz przeglądarki, która nie obsługuje interfejsu File System Observer API, zobacz zrzut ekranu z prezentacją.
Prześlij opinię
Jeśli chcesz podzielić się opinią na temat interfejsu File System Observer API, dodaj komentarz do problemu nr 123 w repozytorium WhatWG/fs.
Powiązane linki
- Wyjaśnienie
- Ocena TAG
- Stanowisko w standardzie Mozilla
- Pozycja w zakresie standardów WebKit
- ChromeStatus
- Błąd Chromium
Podziękowania
Ten dokument zweryfikowali Daseul Lee, Nathan Memmott, Etienne Noël i Rachel Andrew.