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 donnes de formulaire, mais il peut galement tre utilis indpendamment des formulaires pour transmettre des donnes indexes. Le format des donnes transmises est le mme que celui utilis par la mthode submit() du formulaire pour envoyer les donnes lorsque l'encodage de ce dernier est dfini sur multipart/form-data.

Dans cet article

Crer un objet FormData de toutes pices
Rcupration d'un objet FormData dans un formulaire HTML
Envoi de fichiers via un objet FormData
Utiliser un vnement formdata
Points d'attention
Voir aussi

Crer un objet `FormData` de toutes pices

Vous pouvez construire un objet FormData vous-mme, crer une instance, puis y ajouter des champs en appelant la mthode append(), comme suit :

const formData = new FormData();

formData.append("username", "Groucho");
formData.append("accountnum", 123456); // le numro 123456 est converti immdiatement en chane "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 numro attribu au champ accountnum est immdiatement converti en chane par la mthode FormData.append() (la valeur du champ peut tre un objet Blob, File ou une chane : s'il ne s'agit ni d'un objet Blob, ni d'un objet File, la valeur est convertie en chane).

Dans cet exemple, une instance FormData contenant les valeurs des champs username , accountnum , userfile et webmasterfile est cre, puis la mthode XMLHttpRequest.send() est utilise pour envoyer les donnes du formulaire. Le champ webmasterfile est un objet Blob. Un objet Blob reprsente un objet-fichier de donnes brutes immuables. Les blobs reprsentent des donnes qui ne sont pas ncessairement dans un format JavaScript natif. L'interface File se base sur l'objet Blob, elle en hrite les fonctionnalits et les tend pour prendre en charge les fichiers du systme d'exploitation. Pour construire un Blob, vous pouvez invoquer le constructeur Blob().

Rcupration d'un objet `FormData` dans un formulaire HTML

Pour construire un objet FormData contenant les donnes d'un lment HTML <form> existant, spcifiez cet lment lors de la cration 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 donnes supplmentaires l'objet FormData entre la rcupration 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 donnes au formulaire avant de l'envoyer, pour y inclure des informations supplmentaires que les utilisatrices et utilisateurs ne peuvent pas ncessairement modifier.

Envoi de fichiers via un objet `FormData`

L'objet FormData vous permet galement d'envoyer des fichiers. Il vous suffit d'inclure un lment HTML <input> de type file dans votre lment <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  tlverser :
      <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 :

const form = document.forms.namedItem("fileinfo");
form.addEventListener(
  "submit",
  (event) => {
    const output = document.querySelector("#output");
    const formData = new FormData(form);

    formData.append("CustomField", "Des donnes supplmentaires");

    const request = new XMLHttpRequest();
    request.open("POST", "stash.php", true);
    request.onload = (progress) => {
      output.innerHTML =
        request.status === 200
          ? "Fichier tlvers !"
          : `Erreur ${request.status} lors de la tentative de tlversement du fichier.<br />`;
    };

    request.send(formData);
    event.preventDefault();
  },
  false,
);

Note : Si vous passez une rfrence dans le formulaire, la mthode HTTP spcifie dans ce dernier sera utilise au lieu de celle dfinie dans l'appel de la mthode open().

Attention : Lors de l'utilisation de FormData pour envoyer des requtes POST l'aide de XMLHttpRequest ou de l'API Fetch pour du contenu de type multipart/form-data (par exemple pour tlverser des fichiers ou des blobs vers le serveur), il ne faut pas indiquer de faon explicite l'en-tte Content-Type sur la requte. Si vous le faites, cela empchera le navigateur de renseigner l'en-tte Content-Type avec l'expression de limite qui sera utilise pour dlimiter les champs du formulaire dans le corps de la requte.

Vous pouvez galement ajouter un objet File ou Blob directement dans l'objet FormData :

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

Avec la mthode FormData.append(), vous pouvez utiliser le troisime paramtre facultatif pour passer un nom de fichier dans l'en-tte Content-Disposition envoy au serveur. Si aucun nom de fichier n'est spcifi (ou si le paramtre n'est pas pris en charge), le nom blob est utilis.

Utiliser un vnement `formdata`

L'vnement formdata, apparu aprs FormData, est dclench sur un objet HTMLFormElement aprs que la liste des donnes du formulaire a t construite. Cela se produit nativement lors de l'envoi du formulaire, mais peut aussi tre dclench par l'appel au constructeur FormData().

On peut ainsi rcuprer un objet FormData ds le dclenchement de l'vnement formdata, plutt que de l'assembler soi-mme.

Dans cette dmo sur formdata, on fait rfrence au formulaire dans le code JavaScript :

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

Dans le gestionnaire d'vnement pour l'vnement submit, on utilise preventDefault afin d'interrompre l'envoi normal du formulaire, puis on invoque le constructeur FormData() afin de dclencher l'vnement formdata :

formElem.addEventListener("submit", (e) => {
  // lors de l'envoi du formulaire, on empche l'envoi
  // normal
  e.preventDefault();

  // on construit un objet FormData qui dclenche
  // l'vnement formdata
  new FormData(formElem);
});

Lorsque l'vnement formdata se dclenche, on peut accder 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).

formElem.addEventListener("formdata", (e) => {
  console.log("formdata dclench");

  // On rcupre les donnes du formulaire depuis
  // l'objet reprsentant l'vnement
  const data = e.formData;
  for (const value of data.values()) {
    console.log(value);
  }

  // On envoie les donnes via XHR
  const request = new XMLHttpRequest();
  request.open("POST", "/formHandler");
  request.send(data);
});