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` (en-US), 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` (en-US). 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
----------

* Utiliser `XMLHttpRequest`
* `HTMLFormElement`
* `Blob`
* Tableaux typés JavaScript