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. Met de eerste kunnen ontwikkelaars lezen en schrijven naar het gewone, voor de gebruiker zichtbare bestandssysteem, en de laatste opent een speciaal, voor de gebruiker verborgen bestandssysteem dat privé is voor de oorsprong van elke site en dat bepaalde prestatievoordelen met zich meebrengt. De manier waarop ontwikkelaars in beide gevallen omgaan met bestanden en mappen is via FileSystemHandle objecten, meer concreet: FileSystemFileHandle voor bestanden, en FileSystemDirectoryHandle voor mappen. Tot nu toe vereiste het informeren van wijzigingen in een bestand of directory in een van de bestandssystemen een vorm van polling en het vergelijken van de lastModified -tijdstempel of zelfs de bestandsinhoud zelf.

De File System Observer API, een originele proefversie van Chrome 129, brengt daar verandering in en zorgt ervoor dat ontwikkelaars automatisch worden gewaarschuwd wanneer er wijzigingen plaatsvinden. In deze handleiding wordt uitgelegd hoe het werkt en hoe u de functie kunt uitproberen.

Gebruiksgevallen

Gebruik de File System Observer API in apps die op de hoogte moeten worden gesteld van mogelijke wijzigingen in het bestandssysteem zodra deze zich voordoen.

• Webgebaseerde geïntegreerde ontwikkelomgevingen (IDE's) die een weergave tonen van de bestandssysteemboom van een project.
• Apps die wijzigingen in het bestandssysteem synchroniseren met een server. Bijvoorbeeld een SQLite-databasebestand.
• Apps die de hoofdlijn van wijzigingen in het bestandssysteem moeten melden vanaf een werker of een ander tabblad.
• Apps die bijvoorbeeld een directory met bronnen observeren om afbeeldingen automatisch te optimaliseren.
• Ervaringen die profiteren van hot-reloading, zoals op HTML gebaseerde slidedecks waarbij het herladen wordt geactiveerd door een bestandswijziging.

Hoe u de File System Observer-API gebruikt

Functiedetectie

Om te zien 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.
}

Opmerking: Zie de Uitleg voor algemene benaderingen voor het polyfillen van het gedrag van de File System Observer API via polling.

Initialiseer een bestandssysteemwaarnemer

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

const observer = new FileSystemObserver(callback);

Begin met het observeren van een bestand of map

Om te beginnen met het observeren van een bestand of map, roept u de asynchrone observe() -methode van de FileSystemObserver instantie aan. Geef bij deze methode de FileSystemHandle van het geselecteerde bestand of de geselecteerde map op als argument. Wanneer u een map bekijkt, is er een optioneel options argument waarmee u kunt kiezen of u recursief op de hoogte wilt worden gehouden van wijzigingen in de map (dat wil zeggen, voor de map zelf en alle daarin opgenomen submappen en bestanden). De standaardoptie is om alleen de map 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 terugbelfunctie

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

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

Het bestandssysteemwijzigingsrecord

Elk record voor bestandssysteemwijzigingen heeft de volgende structuur. Alle velden zijn alleen-lezen.

• root (a FileSystemHandle ): De handle die wordt doorgegeven aan de FileSystemObserver.observe() functie.
• changedHandle (een FileSystemHandle ): De handle die wordt beïnvloed door de wijziging in het bestandssysteem. Dit veld is null voor gebeurtenissen van het type "errored" , "unknown" en "disappeared" . Gebruik relativePathComponents om te zien welk bestand of welke map is verdwenen.
• relativePathComponents (een Array ): Het pad van de changedHandle ten opzichte van de root .
• type (a String ): Het type wijziging. De volgende typen zijn mogelijk:
  • "appeared" : het bestand of de map is gemaakt of verplaatst naar de root .
  • "disappeared" : het bestand of de map is verwijderd of uit de root verplaatst.
  • "modified" : Het bestand of de map is gewijzigd.
  • "moved" : Het bestand of de map is binnen de root verplaatst.
  • "unknown" : dit geeft aan dat er nul of meer gebeurtenissen zijn gemist. Als reactie hierop moeten ontwikkelaars de bewaakte directory ondervragen.
  • "errored" : De waarneming is niet langer geldig. In dit geval wilt u misschien stoppen met het observeren van het bestandssysteem . Deze waarde wordt ook verzonden wanneer de maximale limiet van waarnemingen per oorsprong wordt bereikt. Deze limiet is afhankelijk van het besturingssysteem en niet vooraf bekend. Als dit gebeurt, kan de site besluiten 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 waargenomen handle (dat wil zeggen 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 waarneming niet langer geldig is. Ten slotte wordt deze gebeurtenis verzonden wanneer de toestemming voor de map of de bestandsingang wordt verwijderd.
• relativePathMovedFrom (een Array , optioneel): De voormalige locatie van een verplaatste handle. Alleen beschikbaar als 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 verandert. In het beste geval ontvangt de website een gedetailleerd wijzigingsrecord met het type wijziging en een handvat voor het betreffende pad. In het slechtste geval ontvangt de website een meer algemene wijzigingsrecord (dat wil zeggen een type met de waarde "unknown" ) waarbij de website nog steeds de directory moet opsommen om erachter te komen welk kind is gewijzigd. Dit is nog steeds een verbetering ten opzichte van polling, omdat de directory-opsomming op aanvraag kan worden gestart vanuit de callback-functie, in plaats van te moeten pollen op veranderingen in intervallen.

Opmerking: op Windows worden "moved" gebeurtenissen niet ondersteund tussen mappen. Ze worden gerapporteerd als "disappeared" in de bronmap en als "appeared" in de doelmap. Ze worden gerapporteerd als "moved" wanneer de bron en het doel zich in dezelfde map bevinden.

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 deze de handle door als argument.

observer.unobserve(fileHandle);

Opmerking: de methode unobserve() wordt niet ondersteund. Gebruik de methode disconnect() als tijdelijke oplossing. Als je geïnteresseerd bent in de voortgang van deze functie, geef dan de functiebug een ster.

Stop met het observeren van het bestandssysteem

Om te stoppen met het observeren van het bestandssysteem, koppelt u de FileSystemObserver -instantie als volgt los.

observer.disconnect();

Probeer de API

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

Demo

U kunt de File System Observer API in actie zien in de ingesloten demo . Bekijk de broncode of remix de democode op Glitch. De demo maakt, verwijdert of wijzigt willekeurig bestanden in een waargenomen map en registreert de activiteit ervan in het bovenste gedeelte van het app-venster. Vervolgens worden de wijzigingen geregistreerd zoals ze plaatsvinden in het onderste deel 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 je feedback hebt over de vorm van de File System Observer API, geef dan commentaar op Issue #123 in de WHATWG/fs -repository.

Relevante koppelingen

• Uitlegger
• TAG-beoordeling
• Mozilla-standaardpositie
• Positie van WebKit-standaarden
• ChromeStatus
• Chroom-bug

Dankbetuigingen

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