L’API `FormData`

FormData est un objet intégré qui représente les champs d’un formulaire et leurs valeurs, et qui convient à un envoi direct via fetch ou XMLHttpRequest. Il gère les téléversements de fichiers, l’encodage multipart et les paires clé-valeur arbitraires sans sérialisation manuelle.

Passez un élément <form> au constructeur : const data = new FormData(formElement). Le résultat contient chaque contrôle de formulaire valide (entrées nommées, listes de sélection, zones de texte, cases à cocher sélectionnées, fichiers). Les contrôles désactivés ou non cochés sont automatiquement exclus.

Passer FormData comme corps de la requête de fetch définit automatiquement le Content-Type de la requête sur multipart/form-data (avec la bonne limite). Ne définissez pas Content-Type manuellement : fetch doit générer lui-même la limite.

data.append(key, value) ajoute une clé (en autorisant les doublons). data.set(key, value) remplace toute valeur existante pour la clé. data.delete(key) supprime toutes les valeurs d’une clé. data.has(key) vérifie sa présence.

FormData gère les fichiers de manière transparente : data.append("avatar", fileInput.files[0]). Le serveur reçoit un téléversement multipart avec le nom et le type MIME du fichier. C’est la méthode standard pour téléverser des fichiers avec fetch dans le code moderne.

FormData est itérable : for (const [key, value] of data) { ... }. Utilisez data.entries(), data.keys() ou data.values() pour des parcours particuliers. C’est utile pour la journalisation, la validation ou la création d’une copie JSON du formulaire.

Pour envoyer les données en JSON plutôt qu’en multipart : Object.fromEntries(data) produit un objet simple, mais perd les clés en double. Pour gérer correctement les doublons, parcourez les entrées et regroupez-les manuellement. Pour les API exclusivement JSON, il est plus simple de construire directement l’objet sans passer par FormData.

Construisez un FormData vide et ajoutez manuellement les valeurs : const data = new FormData(); data.append("title", title); data.append("file", file);. C’est utile pour envoyer des données qui ne proviennent pas d’un formulaire (fichiers déposés par glisser-déposer, réponses d’API, données générées).

Si plusieurs boutons d’envoi existent, passez le bouton utilisé comme deuxième argument à FormData : new FormData(form, e.submitter). Le nom et la valeur de ce bouton sont inclus dans les données, ce qui est important pour les formulaires comportant plusieurs actions.

Pour l’encodage application/x-www-form-urlencoded (l’encodage de formulaire par défaut sans fichiers), construisez un URLSearchParams à partir de FormData : new URLSearchParams(data). Cette méthode est moins coûteuse que multipart pour les formulaires contenant uniquement du texte.

Définir explicitement l’en-tête Content-Type de fetch sur « multipart/form-data » interrompt le téléversement : le navigateur ne peut alors plus ajouter la limite requise. Omettez Content-Type lorsque vous envoyez FormData et laissez fetch s’en charger.

Pourquoi ne devez-vous pas (NOT) définir manuellement Content-Type lorsque vous envoyez FormData avec fetch ?

FormData représente le contenu des formulaires et s’envoie proprement avec fetch, y compris les téléversements de fichiers via multipart/form-data. Créez-le à partir d’un élément de formulaire, ajoutez, définissez ou supprimez les entrées, puis parcourez-les selon vos besoins. Ne définissez pas Content-Type lors de l’envoi : fetch génère automatiquement la limite. Utilisez URLSearchParams pour les formulaires encodés en URL contenant uniquement du texte.