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. Il primo consente agli sviluppatori di leggere e scrivere nel file system normale visibile all'utente, mentre il secondo apre un file system speciale nascosto all'utente, privato dell'origine di ogni sito e con alcuni vantaggi in termini di prestazioni. In entrambi i casi, il modo in cui gli sviluppatori interagiscono con file e directory è tramite oggetti FileSystemHandle, più precisamente FileSystemFileHandle per i file e FileSystemDirectoryHandle per le directory. Fino a questo momento, per essere informati delle modifiche a un file o a una directory in uno dei file system era necessaria una qualche forma di polling e il confronto del timestamp lastModified o addirittura dei contenuti del file stesso.

L'API File System Observer, in prova dell'origine da Chrome 129, cambia la situazione e consente agli sviluppatori di ricevere avvisi automatici quando si verificano modifiche. Questa guida spiega come funziona e come provare la funzionalità.

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 su web che mostrano una rappresentazione dell'albero del file system di un progetto.
  • App che sincronizzano le modifiche al file system con un server. Ad esempio, un file del database SQLite.
  • App che devono notificare al thread principale le modifiche al file system da un worker o un'altra scheda.
  • App che osservano una directory di risorse, ad esempio per ottimizzare automaticamente le immagini.
  • Esperienze che traggono vantaggio dal ricaricamento rapido, come le presentazioni basate su HTML in cui un ricaricamento viene attivato da una modifica del file.

Come utilizzare l'API File System Observer

Rilevamento di funzionalità

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

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

Inizializzare un osservatore del file system

Inizializza un File System Observer chiamando new FileSystemObserver(), fornendo una funzione callback come argomento.

const observer = new FileSystemObserver(callback);

Avviare l'osservazione di un file o di una directory

Per iniziare a osservare un file o una directory, chiama il metodo observe() asincrono dell'istanza FileSystemObserver. Fornisci a questo metodo il FileSystemHandle del file o della directory selezionato come argomento. Quando osservi una directory, è disponibile un argomento facoltativo options che ti consente di scegliere se vuoi ricevere una notifica delle modifiche 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 contenuti 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 vengono apportate modifiche al file system, viene chiamata una funzione di callback con la modifica del file system records e observer stesso come argomenti. Puoi utilizzare l'argomento observer, ad esempio, per scollegare l'osservatore (vedi Interrompere l'osservazione del file system) quando tutti i file che ti interessano sono stati eliminati.

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

Il record di modifica del file system

Ogni record di modifica 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 (a FileSystemHandle): l'handle interessato dalla modifica del file system. Questo campo sarà null per gli eventi di tipo "errored", "unknown" e "disappeared". Per vedere quale file o directory è scomparso, utilizza relativePathComponents.
  • relativePathComponents (un Array): il percorso del changedHandle rispetto al root.
  • type (a String): il tipo di modifica. Sono possibili i seguenti tipi:
    • "appeared": il file o la directory è stato creato o spostato in root.
    • "disappeared": il file o la directory è stato eliminato o spostato fuori da root.
    • "modified": il file o la directory è stato modificato.
    • "moved": il file o la directory è stato spostato all'interno di root.
    • "unknown": indica che sono stati persi zero o più eventi. Gli sviluppatori devono eseguire il polling della directory guardata in risposta.
    • "errored": l'osservazione non è più valida. In questo caso, ti consigliamo di interrompere l'osservazione del file system. Questo valore verrà inviato anche quando viene raggiunto il limite massimo di osservazioni per origine. Questo limite dipende dal sistema operativo e non è noto in anticipo. In questo caso, il sito potrebbe decidere di riprovare, anche se non è garantito che il sistema operativo abbia liberato risorse sufficienti. Un altro caso in cui viene inviato questo valore è quando l'handle osservato (ovvero la radice dell'osservazione) viene eliminato o spostato. In questo caso, viene inviato prima l'evento "disappeared", seguito da un evento "errored", che indica che l'osservazione non è più valida. Infine, questo evento viene inviato quando viene rimossa l'autorizzazione per la directory o l'handle del file.
  • relativePathMovedFrom (un Array, facoltativo): la posizione precedente di un'area di trascinamento spostata. Disponibile solo quando type è "moved".

Interrompere l'osservazione di un file o di una directory

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

observer.unobserve(fileHandle);

Interrompere l'osservazione del file system

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

observer.disconnect();

Prova l'API

Per testare l'API File System Observer localmente, 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 remixa il 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. Poi registra le modifiche man mano che si verificano nella parte inferiore della finestra dell'app. Se stai leggendo queste informazioni 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 problema 123 nel repository WHATWG/fs.

Ringraziamenti

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