Prova dell'origine dell'API File System Observer

Thomas Steiner

L'API File System Access e l'API Origin Private File System consentono entrambe agli sviluppatori di accedere a file e directory sul dispositivo dell'utente. La prima consente agli sviluppatori di leggere e scrivere sul normale file system visibile agli utenti, mentre la seconda apre uno speciale file system nascosto all'utente che è privato per l'origine di ciascun sito e offre determinati vantaggi in termini di prestazioni. Il modo in cui gli sviluppatori interagiscono con i file e le directory in entrambi i casi è attraverso gli oggetti FileSystemHandle, più concretamente, FileSystemFileHandle per i file e FileSystemDirectoryHandle per le directory. Finora, essere informati delle modifiche a un file o a una directory in uno dei file system richiedeva una qualche forma di polling e confronto del timestamp di lastModified o persino dei contenuti del file stesso.

L'API File System Observer, nella prova dell'origine di Chrome 129, modifica questo aspetto e consente agli sviluppatori di essere avvisati automaticamente quando si verificano cambiamenti. Questa guida spiega come funziona e come provarla.

Casi d'uso

Utilizza l'API File System Observer nelle app che devono essere informate di possibili modifiche al file system non appena si verificano.

  • Ambienti di sviluppo integrati (IDE) basati sul web che mostrano una rappresentazione della struttura ad albero del file system di un progetto.
  • App che sincronizzano le modifiche al file system con un server. ad esempio un file di database SQLite.
  • App che devono notificare al thread principale le modifiche al file system da un worker o da un'altra scheda.
  • App che osservano una directory di risorse, ad esempio per ottimizzare automaticamente le immagini.

Come utilizzare l'API File System Observer

Rilevamento delle caratteristiche

Per verificare se l'API File System Observer è supportata, esegui un test delle funzionalità come nell'esempio seguente.

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

Inizializzare un osservatore del file system

Inizializza un osservatore file system chiamando new FileSystemObserver(), fornendo una funzione callback come argomento.

const observer = new FileSystemObserver(callback);

Inizia a osservare un file o una directory

Per iniziare a osservare un file o una directory, chiama il metodo observe() asincrono dell'istanza FileSystemObserver. Fornisci a questo metodo il valore FileSystemHandle del file o della directory selezionati come argomento. Quando osservi una directory, c'è un argomento facoltativo options che ti consente di scegliere se ricevere notifiche sulle modifiche apportate alla directory in modo ricorsivo (ovvero per la directory stessa e per tutte le sottodirectory e i file contenuti). L'opzione predefinita è osservare solo la directory stessa e i file che contiene direttamente.

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

La funzione di callback

Quando si verificano modifiche al file system, viene chiamata una funzione di callback con la modifica del file system records e lo stesso observer come argomento. Puoi utilizzare l'argomento observer, ad esempio, per disconnettere l'osservatore (vedi Smettere di osservare il file system) quando i file che ti interessano vengono tutti eliminati.

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

Record delle modifiche del file system

Ogni record delle modifiche del file system ha la seguente struttura. Tutti i campi sono di sola lettura.

  • root (un FileSystemHandle): l'handle passato alla funzione FileSystemObserver.observe().
  • changedHandle (un FileSystemHandle): l'handle interessato dalla modifica al file system.
  • relativePathComponents (un Array): il percorso di changedHandle relativo a root.
  • type (a String): il tipo di modifica. Sono possibili i seguenti tipi:
    • "appeared": il file o la directory sono stati creati o spostati in root.
    • "disappeared": il file o la directory sono stati eliminati o spostati fuori da root.
    • "modified": il file o la directory sono stati modificati.
    • "moved": il file o la directory è stato spostato all'interno di root.
    • "unknown": indica che sono stati persi zero o più eventi. Gli sviluppatori dovrebbero eseguire il polling della directory controllata in risposta a questo problema.
    • "errored": l'osservazione non è più valida. In questo caso potresti voler interrompere l'osservazione del file system.
  • relativePathMovedFrom (un Array, facoltativo): la posizione precedente di un handle spostato. Disponibile solo quando il valore di type è "moved".
di Gemini Advanced.

Smetti di osservare un file o una directory

Per interrompere l'osservazione di un FileSystemHandle, chiama il metodo unobserve(), passandogli l'handle come argomento.

observer.unobserve(fileHandle);

Smetti di osservare il file system

Per interrompere l'osservazione del file system, disconnetti l'istanza FileSystemObserver come segue.

observer.disconnect();

Prova l'API

Per testare l'API File System Observer in locale, imposta il flag #file-system-observer in about:flags. Per testare l'API con utenti reali, registrati alla prova dell'origine e segui le istruzioni riportate nella guida Prove dell'origine di Chrome. La prova dell'origine verrà eseguita da Chrome 129 (11 settembre 2024) a Chrome 134 (26 febbraio 2025).

Demo

Puoi vedere l'API File System Observer in azione nella demo incorporata. Dai un'occhiata al codice sorgente o esegui il remix del codice demo su Glitch. La demo crea, elimina o modifica in modo casuale i file in una directory osservata e registra la sua attività nella parte superiore della finestra dell'app. Registra quindi le modifiche man mano che vengono eseguite nella parte inferiore della finestra dell'app. Se leggi questo articolo su un browser che non supporta l'API File System Observer, guarda uno screenshot della demo.

Feedback

Se hai un feedback sulla forma dell'API File System Observer, commenta il Numero 123 nel repository WHATWG/fs.

Ringraziamenti

Questo documento è stato esaminato da Daseul Lee, Nathan Memmott, Etienne Noël e Rachel Andrew.