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 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 offre 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, 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 le code temporel lastModified ou même le 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.
}

Remarque :Consultez la présentation pour découvrir les approches générales permettant de polyfiller le comportement de l'API File System Observer via l'interrogation.

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é comme 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 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

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 (voir Arrêter l'observation du 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 a 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. Ce champ sera 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 (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 le 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. Cette valeur est également envoyée lorsque la limite maximale d'observations par origine est 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 d'abord envoyé, suivi d'un événement "errored", qui indique que l'observation n'est plus valide. Enfin, cet événement est envoyé lorsque l'autorisation d'accès au répertoire ou au gestionnaire de fichiers est supprimée.
• relativePathMovedFrom (un Array, facultatif): ancien emplacement d'une poignée déplacée. Disponible uniquement lorsque type est défini sur "moved".

Remarque :En fonction du système d'exploitation, il est possible que tous les événements de modification ne soient pas signalés avec le même niveau de détail, par exemple lorsque le contenu d'un répertoire change de manière récursive. Au mieux, le site Web recevra un enregistrement de modification détaillé contenant le type de modification et un handle vers le chemin d'accès concerné. Dans le pire des cas, le site Web reçoit un enregistrement de modification plus générique (c'est-à-dire un type avec la valeur "unknown") qui nécessite toujours de énumérer le répertoire pour déterminer quel enfant a changé. Il s'agit toujours d'une amélioration par rapport à l'interrogation, car l'énumération des répertoires peut être lancée à la demande à partir de la fonction de rappel, au lieu d'avoir à interroger les modifications à intervalles réguliers.

Remarque :Sous Windows, les événements "moved" ne sont pas compatibles entre les répertoires. Ils sont signalés en tant que "disappeared" à partir du répertoire source et en tant que "appeared" dans le répertoire de destination. Elles sont indiquées comme "moved" lorsque la source et la destination se trouvent dans le même répertoire.

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);

Remarque :La méthode unobserve() n'est pas prise en charge. Pour contourner ce problème, utilisez la méthode disconnect(). Si vous souhaitez suivre l'avancement de cette fonctionnalité, ajoutez une étoile au bug de la fonctionnalité.

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'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 s'étendra 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émo 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 cet article 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, commentez l'problème 123 dans le dépôt WHATWG/fs.

Liens associés

• Explication
• Examen du TAG
• Position de Mozilla sur les normes
• Position de WebKit concernant les normes
• ChromeStatus
• Bug Chromium

Remerciements

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