Phase d'évaluation de l'API File System Observer

Thomas Steiner
Thomas Steiner

L'API File System Access et l'API Origin Private File System permettent aux développeurs d'accéder aux fichiers et répertoires de l'appareil de l'utilisateur. Le premier permet aux développeurs de lire et d'écrire dans le système de fichiers standard visible par l'utilisateur, tandis que le second ouvre un système de fichiers spécial, masqué pour l'utilisateur, qui est privé de l'origine de chaque site et qui présente certains avantages en termes de performances. Dans les deux cas, les développeurs interagissent avec les fichiers et les répertoires via des objets FileSystemHandle. Plus précisément, FileSystemFileHandle pour les fichiers et FileSystemDirectoryHandle pour les répertoires. Jusqu'à présent, être informé des modifications apportées à un fichier ou à un répertoire dans l'un des systèmes de fichiers nécessitait une interrogation et une comparaison de l'horodatage lastModified ou même du contenu du fichier lui-même.

L'API File System Observer, en phase d'évaluation depuis Chrome 129, change cela et permet aux développeurs d'être alertés automatiquement en cas de modification. Ce guide explique son fonctionnement et comment l'essayer.

Cas d'utilisation

Utilisez l'API File System Observer dans les applications qui doivent être informées des modifications possibles du système de fichiers dès qu'elles se produisent.

  • Environnements de développement intégrés (IDE) Web qui affichent une représentation de l'arborescence du système de fichiers d'un projet.
  • Applications qui synchronisent les modifications apportées au système de fichiers avec un serveur. Par exemple, un fichier de base de données SQLite.
  • Applications qui doivent informer le thread principal des modifications apportées au système de fichiers à partir d'un nœud de calcul ou d'un autre onglet.
  • Applications qui observent un répertoire de ressources, par exemple pour optimiser automatiquement les images.
  • Expériences qui profitent du rechargement à chaud, comme les présentations de diapositives basées sur HTML, où un rechargement est déclenché par une modification de fichier.

Utiliser l'API File System Observer

Détection de fonctionnalités

Pour vérifier si l'API File System Observer est compatible, exécutez un test de fonctionnalité comme dans l'exemple suivant.

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

Initialiser un observateur de système de fichiers

Initialisez un observateur de système de fichiers en appelant new FileSystemObserver(), en lui fournissant une fonction callback en tant qu'argument.

const observer = new FileSystemObserver(callback);

Commencer à observer un fichier ou un répertoire

Pour commencer à observer un fichier ou un répertoire, appelez la méthode observe() asynchrone de l'instance FileSystemObserver. Fournissez à cette méthode le FileSystemHandle du fichier ou du répertoire sélectionné en tant qu'argument. Lorsque vous observez un répertoire, un argument options facultatif vous permet de choisir si vous souhaitez être informé des modifications apportées au répertoire de manière récursive (c'est-à-dire pour le répertoire lui-même et tous les sous-répertoires et fichiers qu'il contient). L'option par défaut consiste à n'observer que le répertoire lui-même et les fichiers directement contenus.

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

Fonction de rappel

Lorsqu'il y a des modifications apportées au système de fichiers, une fonction de rappel est appelée avec le changement de système de fichiers records et le observer lui-même comme arguments. Vous pouvez utiliser l'argument observer, par exemple, pour déconnecter l'observateur (consultez la section Arrêter d'observer le système de fichiers) lorsque les fichiers qui vous intéressent sont tous supprimés.

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

Enregistrement de modification du système de fichiers

Chaque enregistrement de modification du système de fichiers présente la structure suivante. Tous les champs sont en lecture seule.

  • root (un FileSystemHandle): poignée transmise à la fonction FileSystemObserver.observe().
  • changedHandle (un FileSystemHandle) : poignée affectée par la modification du système de fichiers.
  • relativePathComponents (un Array): chemin d'accès de changedHandle par rapport à root.
  • type (un String) : type de modification. Les types suivants sont possibles :
    • "appeared" : le fichier ou le répertoire a été créé ou déplacé dans le root.
    • "disappeared" : le fichier ou le répertoire a été supprimé ou déplacé hors du root.
    • "modified": le fichier ou le répertoire a été modifié.
    • "moved": le fichier ou le répertoire a été déplacé dans root.
    • "unknown" : indique qu'un ou plusieurs événements ont été manqués. Les développeurs doivent interroger le répertoire surveillé en réponse à cela.
    • "errored" : l'observation n'est plus valide. Dans ce cas, vous pouvez arrêter d'observer le système de fichiers.
  • relativePathMovedFrom (un Array, facultatif): ancien emplacement d'une poignée déplacée. Disponible uniquement lorsque type est défini sur "moved".

Arrêter l'observation d'un fichier ou d'un répertoire

Pour arrêter l'observation d'un FileSystemHandle, appelez la méthode unobserve() en lui transmettant le gestionnaire en tant qu'argument.

observer.unobserve(fileHandle);

Arrêter l'observation du système de fichiers

Pour arrêter l'observation du système de fichiers, déconnectez l'instance FileSystemObserver comme suit.

observer.disconnect();

Essayer l'API

Pour tester l'API File System Observer en local, définissez l'option #file-system-observer dans about:flags. Pour tester l'API avec de vrais utilisateurs, inscrivez-vous à la phase d'évaluation de l'origine et suivez les instructions du guide Phases d'évaluation de l'origine Chrome. L'évaluation de la fonctionnalité Origin se déroulera de Chrome 129 (11 septembre 2024) à Chrome 134 (26 février 2025).

Démo

Vous pouvez voir l'utilisation de l'API File System Observer dans la démonstration intégrée. Consultez le code source ou remixez le code de démonstration sur Glitch. La démonstration crée, supprime ou modifie de manière aléatoire des fichiers dans un répertoire observé, et consigne son activité dans la partie supérieure de la fenêtre de l'application. Il consigne ensuite les modifications au fur et à mesure qu'elles se produisent dans la partie inférieure de la fenêtre de l'application. Si vous lisez ceci dans un navigateur qui n'est pas compatible avec l'API File System Observer, consultez une capture d'écran de la démonstration.

Commentaires

Si vous avez des commentaires sur la forme de l'API File System Observer, ajoutez des commentaires sur le problème n° 123 dans le dépôt WHATWG/fs.

Remerciements

Ce document a été examiné par Daseul Lee, Nathan Memmott, Étienne Noël et Rachel Andrew.