Utilisation des objets FormData

L'objet FormData vous permet de compiler un ensemble de paires clé/valeur à envoyer à l'aide de l'API XMLHttpRequest. 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éthode submit() du formulaire pour envoyer les données lorsque l'encodage de ce dernier est défini sur multipart/form-data.

Créer un objet FormData de toutes pièces

Vous pouvez construire un objet FormData vous-même, créer une instance, puis y ajouter des champs en appelant la méthode append(), comme suit :

js
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'utilisateur
formData.append("userfile", fileInputElement.files[0]);

// objet JavaScript de type fichier
const content = '<q id="a"><span id="b">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éthode FormData.append() (la valeur du champ peut être un objet Blob, File ou une chaîne : s'il ne s'agit ni d'un objet Blob, ni d'un objet File, la valeur est convertie en chaîne).

Dans cet exemple, une instance FormData contenant les valeurs des champs « username », « accountnum », « userfile » et « webmasterfile » est créée, puis la méthode XMLHttpRequest.send() est utilisée pour envoyer les données du formulaire. Le champ « webmasterfile » est un objet Blob. Un objet Blob 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'interface File se base sur l'objet Blob, elle en hérite les fonctionnalités et les étend pour prendre en charge les fichiers du système d'exploitation. Pour construire un Blob, vous pouvez invoquer le constructeur Blob().

Récupération d'un objet FormData dans un formulaire HTML

Pour construire un objet FormData contenant les données d'un élément HTML <form> existant, spécifiez cet élément lors de la création de l'objet :

js
const formData = new FormData(unElementDeFormulaire);

Par exemple :

js
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'objet FormData entre la récupération depuis le formulaire et son envoi, comme suit :

js
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 objet FormData

L'objet FormData vous permet également d'envoyer des fichiers. Il vous suffit d'inclure un élément HTML <input> de type file dans votre élément <form> :

html
<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&nbsp;:
      <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 id="output"></div>

Vous pouvez ensuite l'envoyer à l'aide du code suivant :

js
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éthode open().

Attention : Lors de l'utilisation de FormData pour envoyer des requêtes POST à l'aide de XMLHttpRequest ou de l'API Fetch pour du contenu de type multipart/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ête Content-Type sur la requête. Si vous le faites, cela empêchera le navigateur de renseigner l'en-tête Content-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 objet File ou Blob directement dans l'objet FormData :

js
data.append("monfichier", monBlob, "nomFichier.txt");

Avec la méthode FormData.append(), vous pouvez utiliser le troisième paramètre facultatif pour passer un nom de fichier dans l'en-tête Content-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ènement formdata

L'évènement formdata, apparu après FormData, est déclenché sur un objet HTMLFormElement 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 constructeur FormData().

On peut ainsi récupérer un objet FormData dès le déclenchement de l'évènement formdata, plutôt que de l'assembler soi-même.

Dans cette démo sur formdata, on fait référence au formulaire dans le code JavaScript :

js
const formElem = document.querySelector("form");

Dans le gestionnaire d'évènement pour l'évènement submit, on utilise preventDefault afin d'interrompre l'envoi normal du formulaire, puis on invoque le constructeur FormData() afin de déclencher l'évènement formdata :

js
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ènement formdata se déclenche, on peut accéder à l'objet FormData en utilisant FormDataEvent.formData. On peut alors le manipuler comme bon nous semble (ici, nous l'envoyons au serveur à l'aide de XMLHttpRequest).

js
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'objet FormData n'inclut pas les données du formulaire pour les champs ou ensembles de champs (<fieldset>) qui sont désactivés.

Voir aussi