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

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 sur l'appareil de l'utilisateur. Le premier permet aux développeurs de lire et d'écrire dans le système de fichiers régulier et visible par l'utilisateur, tandis que le second ouvre un système de fichiers spécial et masqué pour l'utilisateur, qui est privé à 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 par le biais d'objets FileSystemHandle, plus précisément FileSystemFileHandle pour les fichiers et FileSystemDirectoryHandle pour les répertoires. Jusqu'à présent, pour être informé des modifications apportées à un fichier ou à un répertoire dans l'un des systèmes de fichiers, il fallait effectuer une forme d'interrogation et comparer l'horodatage lastModified ou même le contenu du fichier lui-même.

L'API File System Observer, en phase d'évaluation depuis Chrome 129, change la donne et permet aux développeurs d'être avertis automatiquement lorsque des modifications sont apportées. Ce guide explique comment elle fonctionne et comment l'essayer.

Cas d'utilisation

Utilisez l'API File System Observer dans les applications qui doivent être informées des éventuelles modifications 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 du système de fichiers avec un serveur. Par exemple, un fichier de base de données SQLite.
  • Applications qui doivent notifier au thread principal les modifications apportées au système de fichiers par un nœud de calcul ou 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 diaporamas HTML où un rechargement est déclenché par une modification de fichier.

Utiliser l'API File System Observer

Détection de caractéristiques

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 du système de fichiers

Initialisez un observateur du système de fichiers en appelant new FileSystemObserver() et 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 asynchrone observe() de l'instance FileSystemObserver. Fournissez à cette méthode le FileSystemHandle du fichier ou du répertoire sélectionné comme argument. Lors de l'observation d'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 qu'il contient directement.

// 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

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

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

Enregistrement des modifications apportées au 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 (FileSystemHandle) : handle transmis à la fonction FileSystemObserver.observe().
  • changedHandle (FileSystemHandle) : handle concerné par la modification du système de fichiers. Ce champ sera défini sur null pour les événements de type "errored", "unknown" et "disappeared". Pour savoir quel fichier ou répertoire a disparu, utilisez relativePathComponents.
  • relativePathComponents (un Array) : chemin d'accès du changedHandle par rapport au root.
  • type (String) : type de modification. Les types suivants sont possibles :
    • "appeared" : le fichier ou le répertoire a été créé ou déplacé dans root.
    • "disappeared" : le fichier ou le répertoire a été supprimé ou déplacé hors de 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 cesser d'observer le système de fichiers. Cette valeur sera également envoyée lorsque la limite maximale d'observations par origine sera atteinte. Cette limite dépend du système d'exploitation et n'est pas connue à l'avance. Dans ce cas, le site peut décider de réessayer, mais il n'est pas garanti que le système d'exploitation ait libéré suffisamment de ressources. Cette valeur est également envoyée lorsque le handle observé (c'est-à-dire la racine de l'observation) est supprimé ou déplacé. Dans ce cas, l'événement "disappeared" est envoyé en premier, suivi d'un événement "errored", indiquant que l'observation n'est plus valide. Enfin, cet événement est envoyé lorsque l'autorisation d'accès au répertoire ou au fichier est supprimée.
  • relativePathMovedFrom (Array, facultatif) : ancien emplacement d'un handle déplacé. Disponible uniquement lorsque type est "moved".

Arrêter d'observer un fichier ou un répertoire

Pour arrêter d'observer un FileSystemHandle, appelez la méthode unobserve() en lui transmettant le handle comme argument.

observer.unobserve(fileHandle);

Arrêter d'observer le système de fichiers

Pour arrêter d'observer le 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'indicateur #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 l'origine se déroulera de Chrome 129 (11 septembre 2024) à Chrome 134 (26 février 2025).

Démo

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

Commentaires

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

Remerciements

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