File API - Apprendre JavaScript

La File API en JavaScript : interagir avec les fichiers utilisateur

La File API en JavaScript est un outil puissant qui permet aux développeurs web d'interagir avec des fichiers côté client, offrant aux utilisateurs la possibilité de sélectionner, lire et manipuler des fichiers dans des applications web. Cette API trouve de nombreuses applications : téléversement de fichiers, traitement de contenu généré par l'utilisateur, et réalisation d'opérations liées aux fichiers. Dans cet article, nous verrons ce qu'est la File API, ses avantages, les cas où l'utiliser, ainsi que quelques cas d'utilisation courants.

Qu'est-ce que la File API ?

La File API est une API JavaScript qui donne accès aux fichiers sélectionnés par l'utilisateur via des champs de saisie de fichier (<input type="file">) ou des fichiers déposés sur des pages web. Elle expose un petit ensemble d'interfaces qui fonctionnent ensemble :

File — représente un fichier unique sélectionné par l'utilisateur. Il contient des métadonnées telles que name, size (en octets), type (type MIME) et lastModified (un horodatage). Un File est un type spécial de Blob.
Blob — un bloc de données binaires immuables (« Binary Large Object »). Chaque File est un Blob, mais vous pouvez également créer vos propres blobs pour les télécharger ou les envoyer. Consultez le chapitre dédié sur JavaScript Blob pour en savoir plus.
FileList — la collection de type array renvoyée par input.files. Accédez-y avec [0] ou itérez dessus.
FileReader — un lecteur asynchrone qui charge le contenu d'un fichier en mémoire sous forme de texte, d'URL de données ou d'ArrayBuffer.

Comme tout cela s'exécute dans le navigateur, vous pouvez inspecter, valider et prévisualiser des fichiers avant qu'ils n'atteignent un serveur.

La File API lit uniquement les fichiers que l'utilisateur vous confie explicitement. Une page ne peut jamais ouvrir silencieusement des fichiers arbitraires depuis le disque du visiteur — c'est une limite de sécurité délibérée.

Les méthodes de lecture en un coup d'œil

FileReader expose quatre méthodes de lecture. Choisissez celle qui correspond au résultat souhaité :

Méthode	Type de résultat	Utilisation typique
`readAsText(file)`	string	`.txt`, `.csv`, `.json`, code source
`readAsDataURL(file)`	URL `data:` (string)	Aperçu d'image/audio/vidéo via `src`
`readAsArrayBuffer(file)`	`ArrayBuffer`	Analyse binaire, hachage, inspection d'octets
`readAsBinaryString(file)`	string d'octets	Héritage ; préférer `readAsArrayBuffer`

Les navigateurs modernes exposent également des raccourcis basés sur les promesses directement sur le blob : await file.text(), await file.arrayBuffer() et file.stream(). Ceux-ci remplacent souvent FileReader dans le code récent et s'associent naturellement avec async/await.

Quand utiliser la File API

La File API est particulièrement utile lorsque vous souhaitez :

Gérer les téléversements de fichiers — permettre aux utilisateurs de sélectionner et d'envoyer des fichiers depuis leurs appareils.
Prévisualiser des fichiers — afficher une miniature de l'image choisie ou afficher le texte d'un document avant le téléversement.
Valider côté client — rejeter un mauvais type MIME ou un fichier trop volumineux avant de dépenser de la bande passante pour un téléversement.
Manipuler des fichiers localement — recadrer des images, modifier du texte ou analyser des CSV sans aller-retour vers le serveur.

Pour les PDF, notez une réserve : la File API ne génère pas de PDF. Elle ne fait que sélectionner, lire et enregistrer des fichiers. Pour créer un PDF, vous avez besoin d'une bibliothèque comme jsPDF, et la File API (via un Blob) peut ensuite déclencher le téléchargement.

Exemple de base : lire le contenu d'un fichier

Voici un exemple simple utilisant la File API en JavaScript pour lire un fichier texte sélectionné par l'utilisateur et afficher son contenu. Cette démonstration vous aidera à comprendre comment interagir avec des fichiers sur vos appareils à l'aide de technologies web.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>File Reader Example</title>
  </head>
  <body>
    <h1>Read Text File</h1>
    <p>First, choose a text file, then click the 'Read File' button to see your file's contents.</p>
    <input type="file" id="fileInput" accept=".txt" />
    <button onclick="readFile()">Read File</button>
    <pre id="fileContents"></pre>

    <script>
      function readFile() {
        const fileInput = document.getElementById("fileInput");
        const file = fileInput.files[0]; // Get the first file selected by the user

        if (file) {
          const reader = new FileReader();

          reader.onload = function (e) {
            const contents = e.target.result;
            document.getElementById("fileContents").textContent = contents;
          };

          reader.onerror = function (e) {
            console.error("Error reading file:", e.target.error.message);
          };

          reader.readAsText(file); // Read the file as text
        } else {
          alert("Please select a file.");
        }
      }
    </script>
  </body>
</html>

Essayez vous-même »

Dans ce code :

Sélection du fichier : L'utilisateur sélectionne un fichier texte (un fichier avec l'extension .txt) à l'aide de l'élément de saisie de fichier.
Lecture du fichier : Lorsque l'utilisateur clique sur le bouton « Read File », le fichier sélectionné est lu sous forme de texte. Notez que les opérations de FileReader sont asynchrones ; le callback onload s'exécute uniquement une fois que le fichier a été entièrement lu.
Affichage du fichier : Le contenu du fichier est affiché dans un élément <pre>, préservant la mise en forme du fichier texte.

Cet exemple offre une démonstration simple de la capacité de la File API à lire et interagir avec des fichiers sélectionnés par l'utilisateur dans une application web.

Inspecter les métadonnées d'un fichier

Vous avez souvent besoin des détails d'un fichier avant de faire quoi que ce soit d'autre — pour le valider ou montrer à l'utilisateur ce qu'il a sélectionné. Chaque objet File expose ces métadonnées de manière synchrone, sans aucune lecture requise :

const file = fileInput.files[0];

console.log(file.name);          // e.g. "report.pdf"
console.log(file.type);          // MIME type, e.g. "application/pdf"
console.log(file.size);          // size in bytes, e.g. 12048
console.log(file.lastModified);  // ms since the Unix epoch

Une tâche courante consiste à convertir le nombre d'octets en quelque chose de lisible :

function formatBytes(bytes) {
  if (bytes === 0) return "0 B";
  const units = ["B", "KB", "MB", "GB"];
  const i = Math.floor(Math.log(bytes) / Math.log(1024));
  return (bytes / Math.pow(1024, i)).toFixed(1) + " " + units[i];
}

console.log(formatBytes(0));        // "0 B"
console.log(formatBytes(900));      // "900.0 B"
console.log(formatBytes(2048));     // "2.0 KB"
console.log(formatBytes(5242880));  // "5.0 MB"

Valider des fichiers avant le téléversement

La validation côté client offre un retour instantané à l'utilisateur et évite un téléversement inutile. Validez toujours à nouveau côté serveur — les vérifications côté client sont pratiques, mais ne constituent pas une garantie de sécurité, car il est possible de les contourner.

function validateImage(file) {
  const allowedTypes = ["image/png", "image/jpeg", "image/webp"];
  const maxSize = 2 * 1024 * 1024; // 2 MB

  if (!allowedTypes.includes(file.type)) {
    return "Only PNG, JPEG, or WebP images are allowed.";
  }
  if (file.size > maxSize) {
    return "File is too large (max 2 MB).";
  }
  return null; // null means "valid"
}

// Simulate two checks:
console.log(validateImage({ type: "image/gif", size: 1000 }));
// "Only PNG, JPEG, or WebP images are allowed."
console.log(validateImage({ type: "image/png", size: 500 }));
// null

Prévisualiser une image avant le téléversement

Pour afficher une miniature de l'image choisie, lisez-la en tant qu'URL de données et assignez cette string à l'attribut src d'un élément <img>. Le navigateur décode directement la charge utile base64 — aucun serveur n'est impliqué.

<input type="file" id="imageInput" accept="image/*" />
<img id="preview" alt="Preview" width="200" />

<script>
  const input = document.getElementById("imageInput");
  const preview = document.getElementById("preview");

  input.addEventListener("change", () => {
    const file = input.files[0];
    if (!file) return;

    const reader = new FileReader();
    reader.onload = (e) => {
      preview.src = e.target.result; // a "data:image/...;base64,..." URL
    };
    reader.readAsDataURL(file);
  });
</script>

Pour les fichiers médias volumineux, préférez URL.createObjectURL(file) plutôt qu'une URL de données — elle renvoie une courte référence blob: sans copier l'intégralité du fichier dans une string. N'oubliez pas d'appeler URL.revokeObjectURL() lorsque l'aperçu n'est plus nécessaire afin que le navigateur puisse libérer la mémoire.

Lire un fichier avec les promesses modernes

Dans les navigateurs actuels, vous pouvez ignorer FileReader et await les méthodes propres du blob. C'est plus lisible lorsque vous êtes déjà dans une fonction async :

async function readTextFile(file) {
  const text = await file.text();
  return text.trim().split("\n").length; // count of lines
}

// Simulate a File with the same API as the real Blob:
const fakeFile = new Blob(["line 1\nline 2\nline 3"]);
readTextFile(fakeFile).then((lines) => console.log(lines)); // 3

Envoyer un fichier vers un serveur

Une fois un fichier sélectionné, vous pouvez l'envoyer avec fetch et un corps FormData. Le navigateur définit automatiquement les en-têtes multipart/form-data corrects — ne définissez pas Content-Type vous-même :

async function uploadFile(file) {
  const formData = new FormData();
  formData.append("upload", file, file.name);

  const response = await fetch("/api/upload", {
    method: "POST",
    body: formData,
  });
  return response.ok;
}

Consultez le chapitre sur la Fetch API pour le modèle complet de requête/réponse.

Pièges courants

FileReader est asynchrone. Le résultat n'est disponible qu'à l'intérieur de onload ; lire reader.result à la ligne suivante renvoie null.
input.files peut contenir plusieurs fichiers. Ajoutez l'attribut multiple à l'input et itérez sur la FileList ; sinon vous ne verrez jamais que files[0].
La value est effacée à l'annulation dans certains navigateurs. Resélectionner le même fichier peut ne pas déclencher change ; réinitialisez input.value = "" au préalable si vous avez besoin de le détecter.
file.type peut être vide. Pour les extensions inconnues, le type MIME peut être "" ; ne vous y fiez jamais comme seule vérification.
Les Object URL fuient la mémoire. Chaque URL.createObjectURL() doit être accompagné d'un URL.revokeObjectURL().

Conclusion

La File API en JavaScript permet aux développeurs web de travailler directement avec les fichiers utilisateur dans les applications web, ouvrant des possibilités pour enrichir les interactions et offrir une expérience utilisateur fluide. Que vous construisiez un téléverseur de fichiers, un éditeur de documents ou toute application nécessitant la manipulation de fichiers, la File API vous dote des outils nécessaires pour créer des solutions de gestion de fichiers côté client riches en fonctionnalités.

Pour aller plus loin, explorez le chapitre sur JavaScript Blob pour créer et télécharger vos propres données binaires, Drag and Drop avec JavaScript pour permettre aux utilisateurs de déposer des fichiers sur la page, et la Fetch API pour envoyer des fichiers vers un serveur.

Practice

Pratique

Que pouvez-vous faire avec la File API en JavaScript ?

Charger des fichiers texteJouer à un jeuCréer une galerie d'imagesCommander une pizzaGénérer un aperçu en direct des fichiers image