Cette page a été traduite par l'API Cloud Translation.

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 aux 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 standard, visible par l'utilisateur. Le second ouvre un système de fichiers spécial, masqué, réservé à l'origine de chaque site et offrant certains avantages en termes de performances. Dans les deux cas, les développeurs interagissent avec les fichiers et les répertoires via les objets FileSystemHandle, plus concrètement, 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, dans la phase d'évaluation de Chrome 129, modifie cela et permet aux développeurs d'être automatiquement alertés 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 é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 le thread principal des modifications du 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

Utiliser l'API File System Observer

Détection de caractéristiques

Pour savoir 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 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é en tant qu'argument. Lorsque vous observez un répertoire, un argument options facultatif vous permet de choisir si vous souhaitez être informé de manière récursive des modifications apportées au répertoire (c'est-à-dire pour le répertoire lui-même et tous les sous-répertoires et fichiers). L'option par défaut consiste à observer uniquement 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});

La 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, par exemple, pour déconnecter l'observateur (voir 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 des modifications 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): handle transmis à la fonction FileSystemObserver.observe().
changedHandle (un FileSystemHandle): handle affecté 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: <ph type="x-smartling-placeholder">
- "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é à l'extérieur 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'aucun ou plusieurs événements n'ont été manqués. En réponse à cela, les développeurs doivent interroger le répertoire surveillé.
- "errored": l'observation n'est plus valide. Dans ce cas, vous pouvez arrêter d'observer le système de fichiers.
relativePathMovedFrom (Array, facultatif): ancien emplacement d'un identifiant déplacé. Disponible uniquement lorsque type est défini sur "moved".

Remarque :Selon le système d'exploitation, tous les événements de modification peuvent ne pas être 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 détaillé des modifications contenant le type de modification et un identifiant pour le chemin concerné. Au pire, 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 que le site Web énumère le répertoire pour déterminer quel enfant a été modifié. 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 changements d'intervalle.

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 en tant qu'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'option #file-system-observer dans about:flags. Pour tester l'API auprès d'utilisateurs réels, inscrivez-vous à la phase d'évaluation et suivez les instructions décrites dans le guide Phases d'évaluation Chrome. La phase d'évaluation s'exécutera 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 la démo sur Glitch. La démonstration crée, supprime ou modifie les fichiers d'un répertoire observé de manière aléatoire, et consigne son activité dans la partie supérieure de la fenêtre de l'application. Il enregistre ensuite les modifications lorsqu'elles sont apportées 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.

Liens associés

Remerciements

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