API File System

Concepts et utilisation

Cette API permet d'interagir avec les fichiers prsents sur le priphrique local d'une utilisateurice ou sur un systme de fichiers rseau accessible ces derniers. Les fonctionnalits de base incluent la lecture, l'criture ou la sauvegarde de fichiers, ainsi que l'accs la structure des rpertoires.

La plupart des interactions avec les fichiers et les rpertoires se font via des  handles . La classe parente FileSystemHandle permet de dfinir deux classes enfants : FileSystemFileHandle et FileSystemDirectoryHandle, pour les fichiers et les rpertoires respectivement.

Les handles reprsentent un fichier ou un rpertoire sur le systme de l'utilisateurice. Vous pouvez y accder en affichant un slecteur de fichier ou de rpertoire l'aide de mthodes telles que window.showOpenFilePicker() et window.showDirectoryPicker(). Une fois ces mthodes appeles, le slecteur s'affiche et l'utilisateurice choisit un fichier ou un rpertoire. Si la slection est russie, un handle est retourn.

Vous pouvez galement accder aux handles de fichiers via :

• La mthode DataTransferItem.getAsFileSystemHandle() de l'HTML Drag and Drop API.
• L'API de gestion de fichiers (angl.).

Chaque handle offre ses propres fonctionnalits et il existe quelques diffrences selon celui que vous utilisez (voir la section Interfaces pour plus de dtails). Vous pouvez ensuite accder aux donnes des fichiers ou aux informations (y compris les enfants) du rpertoire slectionn. Cette API apporte des fonctionnalits qui faisaient dfaut au Web. Cependant, la scurit a t la principale proccupation lors de la conception de l'API, et l'accs aux fichiers ou rpertoires est interdit sauf si l'utilisateurice l'autorise explicitement (ce qui n'est pas le cas avec le systme de fichiers d'origine priv, qui n'est pas visible pour l'utilisateurice).

Systme de fichiers d'origine priv

Le systme de fichiers d'origine priv (OPFS) est un point de terminaison de stockage fourni dans le cadre de l'API du systme de fichiers, qui est priv pour l'origine de la page et non visible pour l'utilisateurice comme le systme de fichiers classique. Il donne accs un type spcial de fichier hautement optimis pour les performances et offre un accs en criture directe son contenu.

Voici quelques cas d'utilisation possibles :

• Applications avec tlchargement persistant

  • Lorsqu'un fichier ou un rpertoire est slectionn pour tlchargement, vous pouvez copier le fichier dans un bac sable local et tlcharger un morceau la fois.
  • L'application peut reprendre les tlchargements aprs une interruption, comme la fermeture ou le plantage du navigateur, une perte de connexion ou l'arrt de l'ordinateur.

• Jeux vido ou autres applications avec beaucoup de ressources multimdias

  • L'application tlcharge un ou plusieurs gros fichiers (tarballs) et les extrait localement dans une structure de rpertoires.
  • L'application prcharge les ressources en arrire-plan, afin que l'utilisateurice puisse passer au niveau ou la tche suivante sans attendre un tlchargement.

• diteur audio ou photo avec accs hors ligne ou cache local (idal pour les performances et la rapidit)

  • L'application peut crire dans les fichiers en place (par exemple, craser uniquement les balises ID3/EXIF et non le fichier entier).

• Visionnage vido hors ligne

  • L'application peut tlcharger des fichiers volumineux (> 1 Go) pour une visualisation ultrieure.
  • L'application peut accder des fichiers partiellement tlchargs (afin que vous puissiez regarder le premier chapitre d'une vido, mme si l'application est toujours en train de tlcharger le reste du contenu ou si le tlchargement n'est pas termin parce que vous deviez partir).

• Client de messagerie Web hors ligne

  • Le client tlcharge des pices jointes et les stocke localement.
  • Le client met en cache des pices jointes pour un tlchargement ultrieur.

Lisez notre page sur le systme de fichiers d'origine priv pour des instructions sur la faon de l'utiliser.

Enregistrement de fichiers

• Pour les handles asynchrones, utilisez FileSystemWritableFileStream. Une fois que les donnes enregistrer sont dans un format d'objet Blob, String, chane littrale ou buffer, vous pouvez ouvrir un flux et enregistrer les donnes dans un fichier existant ou un nouveau fichier.
• Pour FileSystemSyncAccessHandle (accs synchrone), vous crivez les modifications dans un fichier en utilisant la mthode write(). Vous pouvez galement appeler flush() si vous avez besoin que les modifications soient enregistres sur le disque un moment prcis (sinon, vous pouvez laisser le systme d'exploitation sous-jacent grer cela, ce qui convient dans la plupart des cas).

Interfaces

FileSystemChangeRecord

Contient des dtails d'un seul changement observ par un FileSystemObserver.

FileSystemHandle

Un objet qui reprsente un fichier ou une entre de rpertoire. Plusieurs handles peuvent reprsenter la mme entre. La plupart du temps, vous ne travaillez pas directement avec FileSystemHandle, mais plutt avec ses interfaces enfants FileSystemFileHandle et FileSystemDirectoryHandle.

FileSystemFileHandle

Fournit un handle une entre du systme de fichiers.

FileSystemDirectoryHandle

Fournit un handle un rpertoire du systme de fichiers.

FileSystemObserver

Fournit un mcanisme pour observer les modifications des fichiers ou rpertoires slectionns.

FileSystemSyncAccessHandle

Fournit un handle synchrone une entre du systme de fichiers, qui fonctionne sur un seul fichier du disque. La nature synchrone des lectures et critures de fichiers permet d'obtenir de meilleures performances pour les mthodes critiques dans les contextes o les oprations asynchrones entranent une charge importante, par exemple : WebAssembly. Cette classe n'est accessible qu' l'intrieur des Web Workers ddis pour les fichiers dans le systme de fichiers d'origine priv.

FileSystemWritableFileStream

Un objet WritableStream avec des mthodes supplmentaires pratiques, qui fonctionnent sur un seul fichier sur le disque.

Extensions vers d'autres interfaces

Window.showDirectoryPicker()

Affiche un slecteur de rpertoire qui permet l'utilisateurice de slectionner un rpertoire.

Window.showOpenFilePicker()

Affiche un slecteur de fichiers qui permet une utilisateurice de slectionner un fichier ou plusieurs fichiers.

Window.showSaveFilePicker()

Affiche un slecteur de fichiers qui permet une utilisateurice d'enregistrer un fichier.

DataTransferItem.getAsFileSystemHandle()

Renvoie une Promise (promesse) qui se ralise avec un FileSystemFileHandle si l'lment dplac est un fichier ou s'accompagne avec un FileSystemDirectoryHandle si l'lment dplac est un rpertoire.

StorageManager.getDirectory()

Utilis pour obtenir une rfrence un objet FileSystemDirectoryHandle permettant l'accs un rpertoire et son contenu, stock dans le Systme de fichiers priv d'origine. Renvoie une promesse Promise qui se complte avec un objet FileSystemDirectoryHandle.

Exemples

Accder aux fichiers

Le code ci-dessous permet l'utilisateurice de choisir un fichier dans le slecteur de fichiers.

async function getFile() {
  // Ouvre un slecteur de fichiers et destructure le rsultat pour obtenir le premier lment
  const [fileHandle] = await window.showOpenFilePicker();
  const file = await fileHandle.getFile();
  return file;
}

La fonction asynchrone suivante prsente un slecteur de fichiers et une fois qu'un fichier est choisi, utilise la mthode getFile() pour rcuprer le contenu.

const pickerOpts = {
  types: [
    {
      description: "Images",
      accept: {
        "image/*": [".png", ".gif", ".jpeg", ".jpg"],
      },
    },
  ],
  excludeAcceptAllOption: true,
  multiple: false,
};

async function getTheFile() {
  // Ouvre un slecteur de fichiers et destructure le rsultat pour obtenir le premier lment
  const [fileHandle] = await window.showOpenFilePicker(pickerOpts);

  // obtient le contenu du fichier
  const fileData = await fileHandle.getFile();
}

Accder aux rpertoires

L'exemple suivant renvoie un rpertoire avec le nom spcifi. Si le rpertoire n'existe pas, il est cr.

const dirName = "directoryToGetName";

// il est suppos que nous avons un handle de rpertoire : 'currentDirHandle'
const subDir = currentDirHandle.getDirectoryHandle(dirName, { create: true });

La fonction asynchrone suivante utilise resolve() Pour trouver le chemin d'accs un fichier choisi, par rapport un handle de rpertoire spcifi.

async function returnPathDirectories(directoryHandle) {
  // Ouvre un slecteur de fichiers et destructure le rsultat pour obtenir le premier lment
  const [handle] = await self.showOpenFilePicker();
  if (!handle) {
    // L'utilisateur a annul, ou a chou  ouvrir un fichier.
    return;
  }

  // Vrifie si le handle existe  l'intrieur de notre handle de rpertoire
  const relativePaths = await directoryHandle.resolve(handle);

  if (relativePaths === null) {
    // Pas  l'intrieur du handle de rpertoire
  } else {
    // relativePaths est un tableau de noms, donnant le chemin relatif

    for (const name of relativePaths) {
      // log chaque entre
      console.log(name);
    }
  }
}

criture dans les fichiers

La fonction asynchrone suivante ouvre le slecteur de fichiers de sauvegarde, qui renvoie un FileSystemFileHandle une fois un fichier slectionn. Un flux accessible en criture est ensuite cr l'aide de la mthode FileSystemFileHandle.createWritable().

Un Blob dfini par l'utilisateurice est ensuite crit dans le flux qui est ensuite ferm.

async function saveFile() {
  // cre un nouveau handle
  const newHandle = await window.showSaveFilePicker();

  // cre un FileSystemWritableFileStream pour crire
  const writableStream = await newHandle.createWritable();

  // crit notre fichier
  await writableStream.write(imgBlob);

  // ferme le fichier et crit le contenu sur le disque
  await writableStream.close();
}

Les suivants montrent diffrents exemples d'options qui peuvent tre transmises dans la mthode write().

// juste passer les donnes (pas d'options)
writableStream.write(data);

// crit les donnes dans le flux  partir de la position dtermine
writableStream.write({ type: "write", position, data });

// met  jour le dcalage du curseur de fichier actuel  la position spcifie
writableStream.write({ type: "seek", position });

// redimensionne le fichier pour qu'il fasse la taille spcifie en octets
writableStream.write({ type: "truncate", size });

Lire et crire des fichiers de manire synchrone dans OPFS

Cet exemple lit et crit de manire synchrone un fichier au Systme de fichiers d'origine priv.

La fonction de gestionnaire d'vnements asynchrones suivante est contenue dans un Web Worker. En recevant un message du thread principal, elle :

• Cre une trappe d'accs aux fichiers synchrones.
• Obtient la taille du fichier et cre un ArrayBuffer pour le contenir.
• Lit le contenu du fichier dans le tampon.
• Encode le message et l'crit la fin du fichier.
• Persiste les modifications du disque et ferme la trappe d'accs.

onmessage = async (e) => {
  // rcuprer le message envoy au travail depuis le script principal
  const message = e.data;

  // Obtenir la trappe de fichier de brouillon dans OPFS
  const root = await navigator.storage.getDirectory();
  const draftHandle = await root.getFileHandle("draft.txt", { create: true });
  // Obtenir la trappe d'accs synchrones
  const accessHandle = await draftHandle.createSyncAccessHandle();

  // Obtenir la taille du fichier.
  const fileSize = accessHandle.getSize();
  // Lire le contenu du fichier dans un tampon
  const buffer = new DataView(new ArrayBuffer(fileSize));
  const readBuffer = accessHandle.read(buffer, { at: 0 });

  // crire le message  la fin du fichier
  const encoder = new TextEncoder();
  const encodedMessage = encoder.encode(message);
  const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer });

  // Persister les modifications sur le disque
  accessHandle.flush();

  // Toujours fermer FileSystemSyncAccessHandle si termin
  accessHandle.close();
};

Caractristiques

Compatibilit du navigateur

api.FileSystemHandle

api.FileSystemFileHandle

api.FileSystemDirectoryHandle

api.FileSystemWritableFileStream

api.FileSystemSyncAccessHandle

Voir aussi

• L'API d'accs au systme de fichiers : simplifiant l'accs aux fichiers locaux (angl.)
• Le systme de fichiers d'origine priv (angl.)