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
(unFileSystemHandle
): l'handle passato alla funzioneFileSystemObserver.observe()
.changedHandle
(unFileSystemHandle
): l'handle interessato dalla modifica al file system.relativePathComponents
(unArray
): il percorso dichangedHandle
relativo aroot
.type
(aString
): il tipo di modifica. Sono possibili i seguenti tipi:"appeared"
: il file o la directory sono stati creati o spostati inroot
."disappeared"
: il file o la directory sono stati eliminati o spostati fuori daroot
."modified"
: il file o la directory sono stati modificati."moved"
: il file o la directory è stato spostato all'interno diroot
."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
(unArray
, facoltativo): la posizione precedente di un handle spostato. Disponibile solo quando il valore ditype
è"moved"
.
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.
Link pertinenti
- Spiegazione
- Revisione TAG
- Posizione degli standard di Mozilla
- Posizione degli standard WebKit
- ChromeStatus
- Bug di Chromium
Ringraziamenti
Questo documento è stato esaminato da Daseul Lee, Nathan Memmott, Etienne Noël e Rachel Andrew.