FormData
Rassemble les valeurs des champs d’un formulaire en paires nom-valeur. L’objet obtenu peut être lu ou envoyé au serveur avec fetch().
- Renvoie
- Un nouvel objet
FormData.
Exemple
#const form = document.querySelector('#signup')
const data = new FormData(form)
console.log(data.get('nick'))
console.log(data.get('course'))
console.log(data.get('newsletter'))
console.log(data.get('code'))
console.log(Object.fromEntries(data))Une case cochée sans attribut value a la valeur "on". Le champ désactivé code n’atteint pas du tout les données, donc get() renvoie null pour lui.
Définition et utilisation
#Le constructeur new FormData(form) lit tous les champs du formulaire qui ont un attribut name, et les enregistre sous forme de paires nom-valeur. Vous n’avez pas besoin de récupérer chaque champ séparément : le texte des champs, les cases cochées, les options choisies dans les listes et les fichiers atterrissent tous dans un seul objet. Les champs désactivés (disabled) et les cases non cochées sont ignorés.
La méthode get(nom) renvoie la valeur d’un champ (une chaîne ou un fichier) ou null, getAll() renvoie toutes les valeurs portant ce nom, par exemple de plusieurs cases cochées, et has(), set(), append() et delete() permettent de vérifier et de modifier les données. Object.fromEntries(formData) les transforme en objet ordinaire, mais pour des noms répétés, seule la dernière valeur reste.
Un objet FormData transmis comme body à fetch() est envoyé au format multipart/form-data, le même que celui utilisé par un formulaire ordinaire avec des fichiers. Ne définissez pas l’en-tête Content-Type à la main dans ce cas, car le navigateur doit y ajouter la frontière qui sépare les champs. Si le serveur attend du JSON, convertissez les données en objet ordinaire et envoyez-les avec JSON.stringify().
Syntaxe
#new FormData()
new FormData(form)
new FormData(form, submitter)
formData.get(name)
formData.getAll(name)
formData.has(name)
formData.set(name, value)
formData.append(name, value)
formData.delete(name)Paramètres
#form
élément <form>, optionnel
Le formulaire dont les champs avec un attributnameseront lus.submitter
bouton, optionnel
Le bouton qui a envoyé le formulaire. S’il a des attributsnameetvalue, sa valeur rejoint elle aussi les données.
Plus d’exemples
#const form = document.querySelector('#feedback')
form.addEventListener('submit', (event) => {
event.preventDefault()
const data = new FormData(form, event.submitter)
console.log([...data])
})
form.querySelector('button').click()D’un groupe de boutons radio, seule la valeur cochée est incluse. Le bouton d’envoi figure dans les données parce que nous avons transmis event.submitter comme second argument du constructeur.
const data = new FormData(document.querySelector('#topics'))
console.log(data.get('topic'))
console.log(data.getAll('topic'))
console.log(Object.fromEntries(data))get() ne renvoie que la première valeur, et Object.fromEntries() garde la dernière. Seule getAll() donne tous les sujets cochés.
const form = document.querySelector('#avatar-form')
form.addEventListener('submit', async (event) => {
event.preventDefault()
const data = new FormData(form)
data.append('userId', '42')
const response = await fetch('/api/avatar', { method: 'POST', body: data })
console.log(await response.json())
}){ url: '/avatars/42.webp' }Cet exemple nécessite un serveur, donc il ne s’exécute pas dans l’aperçu, et le résultat est un exemple de réponse d’API. Le fichier du champ <input type="file" name="avatar"> rejoint les données automatiquement, et le navigateur définit lui-même l’en-tête Content-Type.
Compatibilité des navigateurs
#Largement disponible
Fonctionne dans tous les navigateurs modernes, y compris sur mobile. Vous pouvez l’utiliser sans crainte.
- Chrome
- Edge
- Firefox
- Safari
Bonnes pratiques
#- Donnez à chaque champ un attribut
name. Les champs sans attribut n’atteignent jamaisFormData, même s’ils ont une valeur. - En envoyant
FormDataavecfetch(), ne définissez pas l’en-têteContent-Type. Le navigateur l’ajoute lui-même, avec la frontière qui sépare les champs. - Pour plusieurs cases à cocher portant le même nom, utilisez
getAll().get()ne renverra que la première valeur cochée.
Entrées associées
#- Event.preventDefault()Bloque l’action par défaut du navigateur pour un événement, par ex. l’envoi d’un formulaire ou le suivi d’un lien.
- fetch()Envoie une requête HTTP et renvoie une promesse avec la réponse du serveur (un objet Response).
- URLSearchParamsUn objet pour lire et construire les paramètres de requête d’une adresse, la partie après le caractère ?, par exemple ?cours=js&page=2.
- Object.fromEntries()Crée un objet à partir d’une liste de paires [clé, valeur].
- EventTarget.addEventListener()Enregistre une fonction appelée à chaque fois qu’un événement se produit sur un élément, par ex. un clic.
Vous voyez une erreur ou il manque un exemple ? Écrivez-nous.