JavaScript FormData

Gérer efficacement les données de formulaire est essentiel pour créer des pages web dynamiques et interactives. JavaScript fournit l'API FormData exactement dans ce but : elle vous permet de collecter les champs d'un formulaire, de construire des ensembles de paires clé/valeur par programmation, et de les envoyer à un serveur — y compris des fichiers. Ce guide couvre ce qu'est FormData, comment le créer et le lire, toutes les méthodes qu'il expose, comment l'envoyer avec fetch, ainsi que les erreurs courantes à éviter.

Comprendre FormData

FormData est un objet JavaScript intégré qui représente un ensemble de paires clé/valeur, modélisé sur la façon dont un navigateur soumet un formulaire HTML. Il simplifie la collecte d'informations depuis les formulaires HTML et leur envoi asynchrone à un serveur via l'API Fetch.

Pourquoi l'utiliser plutôt que de construire un objet ordinaire ?

• Il lit automatiquement les champs de formulaire existants — pas d'extraction manuelle de value par champ.
• Il prend en charge les fichiers et les Blobs, que les objets ordinaires et JSON ne peuvent pas transporter.
• Lorsqu'il est passé à fetch, le navigateur définit automatiquement le bon Content-Type (multipart/form-data) avec la bonne délimitation.

Créer des objets FormData

Créez un objet FormData avec le constructeur FormData(). Si vous passez un élément <form>, chaque champ nommé et activé de ce formulaire est capturé immédiatement. Vous pouvez inspecter le contenu en itérant sa méthode entries(), qui retourne un itérateur de paires [key, value] :

<script>
  function onSubmit(event) {
    event.preventDefault();
    const form = document.getElementById('myForm');
    const formData = new FormData(form);
    let results = '';
    for (const [key, value] of formData.entries()) {
      results += `${key}: ${value}\n`;
    }
    alert(results)
  }
</script>
<form id="myForm" onsubmit="onSubmit(event)">
  <input type="text" name="username" value="John Doe" />
  <input type="email" name="email" value="[email protected]" />
  <input type="submit" />
</form>

Accéder aux données du formulaire

Lisez un champ unique avec get(), ou parcourez tous les champs avec entries() comme indiqué ci-dessus. get() retourne la première valeur pour une clé (ou null si elle n'existe pas) :

<form id="myForm" onsubmit="onSubmit(event)">
  <input type="text" name="username" value="John Doe" />
  <input type="email" name="email" value="[email protected]" />
  <input type="submit" />
</form>
<script>
  function onSubmit(event) {
    const form = document.getElementById('myForm');
    const formData = new FormData(form);
    const username = formData.get('username');
    const email = formData.get('email');
    alert(`username: ${username}; email: ${email}`);
  }
</script>

Méthodes de FormData

Au-delà de la lecture d'un formulaire existant, FormData vous permet de construire et de modifier manuellement l'ensemble de données. Les méthodes suivantes sont disponibles sur chaque instance :

La différence entre append et set est la source d'erreurs la plus courante :

const fd = new FormData();
fd.append('tag', 'js');
fd.append('tag', 'web');   // append keeps both
console.log(fd.getAll('tag'));   // [ 'js', 'web' ]

fd.set('tag', 'html');     // set replaces all
console.log(fd.getAll('tag'));   // [ 'html' ]

console.log(fd.has('tag'));      // true
fd.delete('tag');
console.log(fd.has('tag'));      // false

Vous pouvez également construire un FormData entièrement par code — sans aucun formulaire — en ajoutant des champs directement. Un troisième argument pour append/set définit le nom de fichier lorsque la valeur est un Blob ou un File.

Envoyer FormData avec l'API Fetch

Un cas d'utilisation courant de FormData est l'envoi asynchrone de données de formulaire au serveur. Passez l'instance FormData comme body d'une requête fetch — le navigateur définit automatiquement le Content-Type à multipart/form-data avec la bonne délimitation, donc ne définissez pas cet en-tête vous-même :

<form id="myForm" onsubmit="onSubmit(event)">
  <input type="text" name="title" value="A title" />
  <input type="text" name="body" value="A body" />
  <input type="submit" value="Submit Post" />
</form>
<div>post id: <span id="response"></span></div>
<script>
  function onSubmit(event) {
    event.preventDefault();
    const form = document.getElementById('myForm');
    const formData = new FormData(form);
    const responseSpan = document.getElementById('response');
    fetch('https://jsonplaceholder.typicode.com/posts', {
        method: 'POST',
        body: formData
    })
      .then(response => response.json())
      .then(data => { responseSpan.innerHTML = data.id; })
      .catch(error => console.error('Error:', error));
  }
</script>

Gérer les téléchargements de fichiers

FormData est la méthode standard pour télécharger des fichiers, car il produit une requête multipart/form-data capable de transporter du contenu binaire aux côtés de champs texte. Lorsque vous construisez le FormData à partir d'un formulaire contenant un <input type="file"> input, le fichier sélectionné est déjà inclus — il n'est pas nécessaire de lire input.files et de l'ajouter à nouveau :

<form id="fileUploadForm">
    <input type="file" name="file" />
    <input type="submit" value="Upload" />
</form>
<script>
    const form = document.getElementById('fileUploadForm');
    form.addEventListener('submit', (event) => {
        event.preventDefault();
        // The file input is captured automatically from the form.
        const formData = new FormData(form);
        fetch('https://httpbin.org/post', {
            method: 'POST',
            body: formData
        })
        .then(response => response.json())
        .then(data => console.log('Upload successful:', data))
        .catch(error => console.error('Error:', error));
    });
</script>

Pour attacher un fichier qui ne fait pas partie d'un formulaire — par exemple un fichier sélectionné par programmation — ajoutez-le explicitement en lui donnant éventuellement un nom de fichier :

const formData = new FormData();
formData.append('avatar', fileObject, 'profile.png');

FormData vs. URLSearchParams

Les deux encapsulent des paires clé/valeur, mais elles se sérialisent différemment. Utilisez FormData lorsque vous devez envoyer des fichiers ou un corps multipart/form-data. Utilisez URLSearchParams lorsque vous n'avez que du texte et souhaitez un corps application/x-www-form-urlencoded compact (ou une chaîne de requête). Vous pouvez même construire l'un depuis l'autre lorsque chaque valeur est une string :

const fd = new FormData();
fd.append('q', 'cats');
fd.append('page', '2');

const params = new URLSearchParams(fd);
console.log(params.toString());   // q=cats&page=2

Conclusion

FormData est un outil polyvalent et puissant pour gérer les données de formulaire dans les applications JavaScript. Que vous traitiez de simples champs texte ou des téléchargements de fichiers complexes, FormData simplifie le processus et fournit une interface pratique pour interagir avec les données de formulaire. En maîtrisant FormData, vous pouvez améliorer l'interactivité et la réactivité de vos applications web, offrant ainsi une expérience utilisateur fluide.

Pratique