Utilisation des objets FormData
L'objetFormData vous permet de compiler un ensemble de paires clé/valeur à envoyer à l'aide de l'APIXMLHttpRequest. Il est principalement destiné à l'envoi de données de formulaire, mais il peut également être utilisé indépendamment des formulaires pour transmettre des données indexées. Le format des données transmises est le même que celui utilisé par la méthodesubmit() du formulaire pour envoyer les données lorsque l'encodage de ce dernier est défini surmultipart/form-data.
Créer un objetFormData de toutes pièces
Vous pouvez construire un objetFormData vous-même, créer une instance, puis y ajouter des champs en appelant la méthodeappend(), comme suit :
const formData = new FormData();formData.append("username", "Groucho");formData.append("accountnum", 123456); // le numéro 123456 est converti immédiatement en chaîne "123456"// fichier HTML choisi par l'utilisateurformData.append("userfile", fileInputElement.files[0]);// objet JavaScript de type fichierconst content = '<q><span>hey!</span></q>'; // le corps du nouveau fichier…const blob = new Blob([content], { type: "text/xml" });formData.append("webmasterfile", blob);const request = new XMLHttpRequest();request.open("POST", "https://example.com/submitform.php");request.send(formData);Note :Les champs « userfile » et « webmasterfile » contiennent tous deux un fichier. Le numéro attribué au champ « accountnum » est immédiatement converti en chaîne par la méthodeFormData.append() (la valeur du champ peut être un objetBlob,File ou une chaîne :s'il ne s'agit ni d'un objetBlob, ni d'un objetFile, la valeur est convertie en chaîne).
Dans cet exemple, une instanceFormData contenant les valeurs des champs « username », « accountnum », « userfile » et « webmasterfile » est créée, puis la méthodeXMLHttpRequest.send() est utilisée pour envoyer les données du formulaire. Le champ « webmasterfile » est un objetBlob. Un objetBlob représente un objet-fichier de données brutes immuables. Les blobs représentent des données qui ne sont pas nécessairement dans un format JavaScript natif. L'interfaceFile se base sur l'objetBlob, elle en hérite les fonctionnalités et les étend pour prendre en charge les fichiers du système d'exploitation. Pour construire unBlob, vous pouvez invoquerle constructeurBlob().
Récupération d'un objetFormData dans un formulaire HTML
Pour construire un objetFormData contenant les données d'un élément HTML<form> existant, spécifiez cet élément lors de la création de l'objet :
const formData = new FormData(unElementDeFormulaire);Par exemple :
const formElement = document.querySelector("form");const request = new XMLHttpRequest();request.open("POST", "submitform.php");request.send(new FormData(formElement));Vous pouvez également ajouter des données supplémentaires à l'objetFormData entre la récupération depuis le formulaire et son envoi, comme suit :
const formElement = document.querySelector("form");const formData = new FormData(formElement);const request = new XMLHttpRequest();request.open("POST", "submitform.php");formData.append("serialnumber", serialNumber++);request.send(formData);Vous pouvez ainsi ajouter des données au formulaire avant de l'envoyer, pour y inclure des informations supplémentaires que les utilisatrices et utilisateurs ne peuvent pas nécessairement modifier.
Envoi de fichiers via un objetFormData
L'objetFormData vous permet également d'envoyer des fichiers. Il vous suffit d'inclure un élément HTML<input> de typefile dans votre élément<form> :
<form enctype="multipart/form-data" method="post" name="fileinfo"> <p> <label >Votre adresse électronique : <input type="email" autocomplete="on" name="userid" placeholder="email" required size="32" maxlength="64" /> </label> </p> <p> <label >Nom personnalisé pour le fichier : <input type="text" name="filelabel" size="12" maxlength="32" /> </label> </p> <p> <label >Fichier à téléverser : <input type="file" name="file" required /> </label> </p> <p> <input type="submit" value="Envoyer le fichier !" /> </p></form><div></div>Vous pouvez ensuite l'envoyer à l'aide du code suivant :
const form = document.forms.namedItem("fileinfo");form.addEventListener( "submit", (event) => { const output = document.querySelector("#output"); const formData = new FormData(form); formData.append("CustomField", "Des données supplémentaires"); const request = new XMLHttpRequest(); request.open("POST", "stash.php", true); request.onload = (progress) => { output.innerHTML = request.status === 200 ? "Fichier téléversé !" : `Erreur ${request.status} lors de la tentative de téléversement du fichier.<br />`; }; request.send(formData); event.preventDefault(); }, false,);Note :Si vous passez une référence dans le formulaire,la méthode HTTP spécifiée dans ce dernier sera utilisée au lieu de celle définie dans l'appel de la méthodeopen().
Attention :Lors de l'utilisation deFormData pour envoyer des requêtes POST à l'aide deXMLHttpRequest ou del'APIFetch pour du contenu de typemultipart/form-data (par exemple pour téléverser des fichiers ou des blobs vers le serveur),il ne faut pas indiquer de façon explicite l'en-têteContent-Type sur la requête. Si vous le faites, cela empêchera le navigateur de renseigner l'en-têteContent-Type avec l'expression de limite qui sera utilisée pour délimiter les champs du formulaire dans le corps de la requête.
Vous pouvez également ajouter un objetFile ouBlob directement dans l'objetFormData :
data.append("monfichier", monBlob, "nomFichier.txt");Avec la méthodeFormData.append(), vous pouvez utiliser le troisième paramètre facultatif pour passer un nom de fichier dans l'en-têteContent-Disposition envoyé au serveur. Si aucun nom de fichier n'est spécifié (ou si le paramètre n'est pas pris en charge), le nom « blob » est utilisé.
Utiliser un évènementformdata
L'évènementformdata, apparu aprèsFormData, est déclenché sur un objetHTMLFormElement après que la liste des données du formulaire a été construite. Cela se produit nativement lors de l'envoi du formulaire, mais peut aussi être déclenché par l'appel au constructeurFormData().
On peut ainsi récupérer un objetFormData dès le déclenchement de l'évènementformdata, plutôt que de l'assembler soi-même.
Danscette démo surformdata, on fait référence au formulaire dans le code JavaScript :
const formElem = document.querySelector("form");Dans le gestionnaire d'évènement pourl'évènementsubmit, on utilisepreventDefault afin d'interrompre l'envoi normal du formulaire, puis on invoque le constructeurFormData() afin de déclencher l'évènementformdata :
formElem.addEventListener("submit", (e) => { // lors de l'envoi du formulaire, on empêche l'envoi // normal e.preventDefault(); // on construit un objet FormData qui déclenche // l'évènement formdata new FormData(formElem);});Lorsque l'évènementformdata se déclenche, on peut accéder à l'objetFormData en utilisantFormDataEvent.formData. On peut alors le manipuler comme bon nous semble (ici, nous l'envoyons au serveur à l'aide deXMLHttpRequest).
formElem.addEventListener("formdata", (e) => { console.log("formdata déclenché"); // On récupère les données du formulaire depuis // l'objet représentant l'évènement const data = e.formData; for (const value of data.values()) { console.log(value); } // On envoie les données via XHR const request = new XMLHttpRequest(); request.open("POST", "/formHandler"); request.send(data);});Points d'attention
L'objetFormData n'inclut pas les données du formulaire pour les champs ou ensembles de champs (<fieldset>) qui sont désactivés.