Questa pagina è stata tradotta dall'API Cloud Translation.

Prova dell'origine dell'API File System Observer

Thomas Steiner

L'API File System Access e l'API Origin Private File System consentono 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 per l'origine di ogni sito e che offre alcuni vantaggi in termini di prestazioni. In entrambi i casi, gli sviluppatori interagiscono con file e directory tramite oggetti FileSystemHandle, più precisamente FileSystemFileHandle per i file e FileSystemDirectoryHandle per le directory. Fino ad ora, per essere informati delle modifiche a un file o a una directory in uno dei file system era necessario eseguire un polling e confrontare il timestamp lastModified o persino i contenuti del file.

L'API File System Observer, in prova dell'origine da Chrome 129, cambia questa 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 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.
Esperienze che traggono vantaggio dal ricaricamento rapido, come i file di presentazione basati su HTML in cui un ricaricamento viene attivato da una modifica del file.

Come utilizzare l'API File System Observer

Rilevamento delle funzionalità

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 del file system chiamando new FileSystemObserver(), fornendo una funzione callback come argomento.

const observer = new FileSystemObserver(callback);

Iniziare a osservare un file o una directory

Per iniziare a osservare un file o una directory, chiama il metodo asincrono observe() dell'istanza FileSystemObserver. Fornisci a questo metodo il FileSystemHandle del file o della directory selezionati come argomento. Quando osservi una directory, è presente un argomento options facoltativo che ti consente di scegliere se vuoi essere informato delle modifiche alla directory in modo ricorsivo (ovvero per la directory stessa e per tutti i file e le sottodirectory contenuti). L'opzione predefinita prevede di 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 si verificano modifiche al file system, viene chiamata una funzione di callback con la modifica del file system records e lo stesso observer come argomenti. Puoi utilizzare l'argomento observer per, ad esempio, disconnettere l'osservatore (vedi Interrompere l'osservazione del file system) quando tutti i file che ti interessano vengono 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 (un 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 di changedHandle relativo a root.
type (un 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 monitorata in risposta a questa azione.
- "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 questo valore verrà inviato è 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 l'handle di directory o file.
relativePathMovedFrom (un Array, facoltativo): la posizione precedente di un handle spostato. Disponibile solo quando type è "moved".

Nota: a seconda del sistema operativo, non tutti gli eventi di modifica potrebbero essere segnalati con lo stesso livello di dettaglio, ad esempio quando i contenuti di una directory cambiano in modo ricorsivo. Nel migliore dei casi, il sito web riceverà un record di modifica dettagliato contenente il tipo di modifica e un handle del percorso interessato. Nel peggiore dei casi, il sito web riceve un record di modifica più generico (ovvero un type con il valore "unknown") che richiede comunque al sito web di enumerare la directory per capire quale figlio è cambiato. Si tratta comunque di un miglioramento rispetto al polling, in quanto l'enumerazione delle directory può essere avviata on demand dalla funzione di callback, anziché dover eseguire il polling per rilevare le modifiche a intervalli.

Interrompere l'osservazione di un file o una directory

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

observer.unobserve(fileHandle);

Interrompere l'osservazione del 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 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. 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. Quindi, registra le modifiche man mano che si verificano 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 feedback sulla forma dell'API File System Observer, commenta il problema n. 123 nel repository WHATWG/fs.

Link pertinenti

Ringraziamenti

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