Deze pagina is vertaald door de Cloud Translation API.

De File System Observer API-originele proefversie

Thomas Steiner

De File System Access API en de Origin Private File System API geven ontwikkelaars beide toegang tot bestanden en mappen op het apparaat van de gebruiker. De eerste laat ontwikkelaars lezen en schrijven naar het reguliere, voor de gebruiker zichtbare bestandssysteem, en de tweede opent een speciaal, voor de gebruiker verborgen bestandssysteem dat privé is voor de oorsprong van elke site en dat bepaalde prestatievoordelen biedt. Ontwikkelaars werken in beide gevallen met bestanden en mappen via FileSystemHandle objecten, meer concreet FileSystemFileHandle voor bestanden en FileSystemDirectoryHandle voor mappen. Tot nu toe was het verkrijgen van informatie over wijzigingen in een bestand of map in beide bestandssystemen een vorm van polling en vergelijking van de lastModified -tijdstempel of zelfs de bestandsinhoud zelf vereist.

De File System Observer API, waarvan de oorspronkelijke proefversie van Chrome 129 is, brengt daar verandering in en zorgt ervoor dat ontwikkelaars automatisch worden gewaarschuwd wanneer er wijzigingen plaatsvinden. Deze handleiding legt uit hoe het werkt en hoe u de functie kunt uitproberen.

Gebruiksscenario's

Gebruik de File System Observer API in apps die zo snel mogelijk op de hoogte moeten worden gebracht van mogelijke wijzigingen in het bestandssysteem.

Op internet gebaseerde geïntegreerde ontwikkelomgevingen (IDE's) die een weergave van de bestandssysteemboom van een project tonen.
Apps die wijzigingen in het bestandssysteem synchroniseren met een server. Bijvoorbeeld een SQLite-databasebestand.
Apps die de hoofdthread via een worker of een ander tabblad op de hoogte moeten stellen van wijzigingen in het bestandssysteem.
Apps die een directory van bronnen in acht nemen, bijvoorbeeld om automatisch afbeeldingen te optimaliseren.
Ervaringen die profiteren van hot-reloading, zoals HTML-gebaseerde diapresentaties waarbij het opnieuw laden wordt geactiveerd door een bestandswijziging.

Hoe de File System Observer API te gebruiken

Functiedetectie

Om te controleren of de File System Observer API wordt ondersteund, voert u een functietest uit zoals in het volgende voorbeeld.

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

Initialiseer een bestandssysteemobservator

Initialiseer een File System Observer door new FileSystemObserver() aan te roepen en geef deze een callback -functie als argument mee.

const observer = new FileSystemObserver(callback);

Begin met het observeren van een bestand of map

Om een bestand of directory te observeren, roept u de asynchrone observe() methode van de FileSystemObserver instantie aan. Geef deze methode de FileSystemHandle van het geselecteerde bestand of de geselecteerde directory als argument. Bij het observeren van een directory is er een optioneel options argument waarmee u kunt kiezen of u recursief op de hoogte wilt worden gehouden van wijzigingen in de directory (dat wil zeggen, voor de directory zelf en alle daarin opgenomen subdirectory's en bestanden). De standaardoptie is om alleen de directory zelf en de direct daarin opgenomen bestanden te observeren.

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

De callback-functie

Wanneer er wijzigingen in het bestandssysteem plaatsvinden, wordt een callbackfunctie aangeroepen met de records van het bestandssysteem en de observer zelf als argumenten. U kunt het observer argument gebruiken om bijvoorbeeld de verbinding met de observer te verbreken (zie Stoppen met het observeren van het bestandssysteem ) wanneer alle bestanden waarin u geïnteresseerd bent, zijn verwijderd.

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

Het wijzigingsrecord van het bestandssysteem

Elk wijzigingsrecord in het bestandssysteem heeft de volgende structuur: alle velden zijn alleen-lezen.

root (een FileSystemHandle ): De handle die wordt doorgegeven aan de FileSystemObserver.observe() functie.
changedHandle (een FileSystemHandle ): De handle die door de wijziging in het bestandssysteem is beïnvloed. Dit veld is null voor gebeurtenissen van het type "errored" , "unknown" en "disappeared" . Gebruik relativePathComponents om te zien welk bestand of welke directory verdwenen is.
relativePathComponents (een Array ): Het pad van de changedHandle relatief ten opzichte van de root .
type (een String ): Het type van de wijziging. De volgende typen zijn mogelijk:
- "appeared" : Het bestand of de map is aangemaakt of verplaatst naar de root .
- "disappeared" : Het bestand of de map is verwijderd of verplaatst uit de root .
- "modified" : Het bestand of de map is gewijzigd.
- "moved" : Het bestand of de map is verplaatst binnen de root .
- "unknown" : Dit geeft aan dat er nul of meer gebeurtenissen zijn gemist. Ontwikkelaars moeten de bewaakte directory hierop controleren.
- "errored" : De observatie is niet langer geldig. In dit geval kunt u het bestandssysteem beter niet meer observeren . Deze waarde wordt ook verzonden wanneer de maximale limiet voor observaties per oorsprong is bereikt. Deze limiet is afhankelijk van het besturingssysteem en vooraf niet bekend. Als dit gebeurt, kan de site besluiten om het opnieuw te proberen, hoewel er geen garantie is dat het besturingssysteem voldoende bronnen heeft vrijgemaakt. Een ander geval waarin deze waarde wordt verzonden, is wanneer de geobserveerde handle (d.w.z. de root van de observatie) wordt verwijderd of verplaatst. In dit geval wordt eerst de gebeurtenis "disappeared" verzonden, gevolgd door een gebeurtenis "errored" , die aangeeft dat de observatie niet langer geldig is. Ten slotte wordt deze gebeurtenis verzonden wanneer de machtiging voor de directory of bestandshandle wordt verwijderd.
relativePathMovedFrom (een Array , optioneel): De voormalige locatie van een verplaatste handle. Alleen beschikbaar wanneer het type "moved" is.

Opmerking: Afhankelijk van het besturingssysteem worden mogelijk niet alle wijzigingsgebeurtenissen met hetzelfde detailniveau gerapporteerd, bijvoorbeeld wanneer de inhoud van een directory recursief wordt gewijzigd. In het beste geval ontvangt de website een gedetailleerd wijzigingsrecord met het type wijziging en een handle naar het betreffende pad. In het slechtste geval ontvangt de website een meer generiek wijzigingsrecord (dat wil zeggen een type met de waarde "unknown" ), waarbij de website nog steeds de directory moet inventariseren om te bepalen welk subbestand is gewijzigd. Dit is nog steeds een verbetering ten opzichte van polling, omdat de directory-enumeratie op aanvraag kan worden gestart vanuit de callbackfunctie, in plaats van dat er met tussenpozen naar wijzigingen moet worden gepolst.

Stop met het observeren van een bestand of map

Om te stoppen met het observeren van een FileSystemHandle , roept u de methode unobserve() aan en geeft u de handle als argument door.

observer.unobserve(fileHandle);

Stop met het observeren van het bestandssysteem

Om het observeren van het bestandssysteem te stoppen, verbreekt u de verbinding met het FileSystemObserver -exemplaar als volgt.

observer.disconnect();

Probeer de API

Om de File System Observer API lokaal te testen, stelt u de vlag #file-system-observer in in about:flags . Om de API met echte gebruikers te testen, meldt u zich aan voor de Origin-proefversie en volgt u de instructies in de handleiding Chrome Origin Trials . De Origin-proefversie loopt van Chrome 129 (11 september 2024) tot Chrome 134 (26 februari 2025).

Demonstratie

U kunt de File System Observer API in actie zien in de ingesloten demo . Bekijk de broncode . De demo maakt, verwijdert of wijzigt willekeurig bestanden in een geobserveerde directory en registreert de activiteit ervan in het bovenste gedeelte van het app-venster. Vervolgens registreert het de wijzigingen zodra ze plaatsvinden in het onderste gedeelte van het app-venster. Als u dit leest in een browser die de File System Observer API niet ondersteunt, bekijk dan een screenshot van de demo.

Feedback

Als u feedback hebt over de vormgeving van de File System Observer API, reageer dan op Issue #123 in de WHATWG/fs repository.

Relevante links

Dankbetuigingen

Dit document is beoordeeld door Daseul Lee , Nathan Memmott , Etienne Noël en Rachel Andrew .