1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
---
title: Utiliser les objets FormData
slug: conflicting/Web/API/FormData/Using_FormData_Objects
translation_of: Web/API/FormData/Using_FormData_Objects
translation_of_original: Web/Guide/Using_FormData_Objects
original_slug: Web/Guide/Using_FormData_Objects
---
<p>L'objet <a href="/en/DOM/XMLHttpRequest/FormData" title="en/DOM/XMLHttpRequest/FormData"><code>FormData</code></a> vous permet de créer un ensemble de paires clef-valeur pour un envoi via <code>XMLHttpRequest</code>. Cet objet est destiné avant tout à l'envoi de données de formulaire, mais il peut être utilisé indépendamment des formulaires afin de transmettre des données associées à une clef. Les données transmises sont dans le même format qu'utiliserait la méthode <code>submit()</code> pour envoyer des données si le type d'encodage du formulaire correspondait à "multipart/form-data".</p>
<h2 id="Créer_un_objet_FormData_de_zéro">Créer un objet <code>FormData</code> de zéro</h2>
<p>Vous pouvez créer un objet <code>FormData</code> en l'instanciant puis en lui ajoutant des champs au moyen de la méthode <a href="/en/DOM/XMLHttpRequest/FormData#append()" title="en/XMLHttpRequest/FormData#append()"><code>append()</code></a>, comme ci-dessous :</p>
<pre class="brush: js">var formData = new FormData();
formData.append("username", "Groucho");
formData.append("accountnum", 123456); // le nombre 123456 est immédiatement converti en la chaîne "123456"
// Choix de l'utilisateur à partir d'un input HTML de type file...
formData.append("userfile", fileInputElement.files[0]);
// Pseudo-objet fichier JavaScript...
var content = '<a id="a"><b id="b">hey!</b></a>'; // le corps du nouveau fichier...
var blob = new Blob([content], { type: "text/xml"});
formData.append("webmasterfile", blob);
var request = new XMLHttpRequest();
request.open("POST", "http://foo.com/submitform.php");
request.send(formData);
</pre>
<div class="note"><strong>Remarque :</strong> les champs "userfile" et "webmasterfile" contiennent tous les deux un fichier. Le nombre assigné au champ "accountnum" est immédiatement converti en une chaîne de caractères par la méthode <a href="/en/DOM/XMLHttpRequest/FormData#append()" title="en/XMLHttpRequest/FormData#append()"><code>FormData.append()</code></a> (la valeur du champ peut être soit un {{ domxref("Blob") }}, soit un {{ domxref("File") }}, ou encore une chaîne de caractères : <strong>si la valeur n'est ni un objet Blob ni un objet File, la valeur est convertie en une chaîne de caractères</strong>).</div>
<p>Cet exemple crée une instance de <code>FormData</code> contenant des valeurs pour les champs nommés "username", "accountnum", "userfile" et "webmasterfile", puis utilise la méthode <a href="/en/DOM/XMLHttpRequest#send()" title="en/XMLHttpRequest#send()"><code>send()</code></a> de <code>XMLHttpRequest</code> pour envoyer les données du formulaire. Le champ "webmasterfile" est un <a href="/en/DOM/Blob" title="en/DOM/Blob"><code>Blob</code></a>. Un objet <a href="/en/DOM/Blob" title="en/DOM/Blob"><code>Blob</code></a> représente un pseudo-objet fichier de données brutes et immuables. Les Blobs représentent des données qui ne sont pas forcément dans un format natif de JavaScript. L'interface {{ domxref("File") }} est basée sur le <a href="/en/DOM/Blob" title="en/DOM/Blob"><code>Blob</code></a>, héritant des fonctionnalités du blob et l'étendant afin de supporter les fichiers système de l'utilisateur. Afin de construire un <a href="/en/DOM/Blob" title="en/DOM/Blob"><code>Blob</code></a>, vous pouvez invoquer le <a href="/en/DOM/Blob#Constructor" title="en/DOM/Blob#Constructor"><code>constructeur Blob</code></a>.</p>
<h2 id="Récupérer_un_objet_FormData_à_partir_d'un_formulaire">Récupérer un objet <code>FormData</code> à partir d'un formulaire</h2>
<p>Pour construire un objet <code>FormData</code> qui contient les données d'un {{ HTMLElement("form") }} existant, il suffit de spécifier cet élément formulaire lors de la création de l'objet <code>FormData</code> :</p>
<pre class="brush: js">var formData = new FormData(someFormElement);
</pre>
<p>Par exemple :</p>
<pre class="brush: js">var formElement = document.getElementById("myFormElement");
var request = new XMLHttpRequest();
request.open("POST", "submitform.php");
request.send(new FormData(formElement));
</pre>
<p>Vous pouvez également ajouter des données additionnelles à l'objet <code>FormData</code> après l'avoir extrait d'un formulaire et avant son envoi, comme ceci :</p>
<pre class="brush: js">var formElement = document.getElementById("myFormElement");
formData = new FormData(formElement);
formData.append("serialnumber", serialNumber++);
request.send(formData);</pre>
<p>Cela vous permet de compléter les données du formulaire avant de les envoyer, en incluant des informations additionnelles qui ne sont pas nécessairement accessibles à l'utilisateur dans le formulaire.</p>
<h2 id="Envoyer_des_fichiers_avec_un_objet_FormData">Envoyer des fichiers avec un objet <code>FormData</code></h2>
<p>Vous pouvez aussi envoyer des fichiers en utilisant <code>FormData</code>. Il suffit d'inclure un élément {{ HTMLElement("input") }} de type "file" :</p>
<pre class="brush: html"><form enctype="multipart/form-data" method="post" name="fileinfo">
<label>Your email address:</label>
<input type="email" autocomplete="on" autofocus name="userid" placeholder="email" required size="32" maxlength="64" /><br />
<label>Custom file label:</label>
<input type="text" name="filelabel" size="12" maxlength="32" /><br />
<label>File to stash:</label>
<input type="file" name="file" required />
<input type="submit" value="Stash the file!" />
</form>
<div id="output"></div>
</pre>
<p>Vous pouvez ensuite l'envoyer en utilisant un code semblable à celui-ci :</p>
<pre class="brush: js">var form = document.forms.namedItem("fileinfo");
form.addEventListener('submit', function(ev) {
var
oOutput = document.getElementById("output"),
oData = new FormData(document.forms.namedItem("fileinfo"));
oData.append("CustomField", "This is some extra data");
var oReq = new XMLHttpRequest();
oReq.open("POST", "stash.php", true);
oReq.onload = function(oEvent) {
if (oReq.status == 200) {
oOutput.innerHTML = "Uploaded!";
} else {
oOutput.innerHTML = "Error " + oReq.status + " occurred uploading your file.<br \/>";
}
};
oReq.send(oData);
ev.preventDefault();
}, false);
</pre>
<div class="note">
<p><strong>Remarque </strong>: si vous passez une référence au formulaire, la méthode spécifiée dans le formulaire sera utilisée en remplacement de celle précisée dans l'appel à open().</p>
</div>
<div class="note">
<p><strong>Remarque </strong>: Cet exemple redirige les données en sortie vers un script PHP sur le serveur, et gère les erreurs HTTP, quoique d'une manière peu élégante.</p>
</div>
<p>Vous pouvez aussi ajouter un {{ domxref("File") }} ou un {{ domxref("Blob") }} directement à l'objet {{ domxref("XMLHttpRequest/FormData", "FormData") }}, comme ceci :</p>
<pre class="brush: js">data.append("myfile", myBlob, "filename.txt");
</pre>
<p>Lorsque la méthode <code>append</code> est utilisée, il est possible de renseigner le troisième paramètre optionnel pour passer un nom de fichier à l'en-tête <code>Content-Disposition</code> qui est envoyée au serveur. Si aucun nom de fichier n'est spécifié (ou si le paramètre n'est pas supporté,) le nom "blob" est utilisé.</p>
<p>Vous pouvez aussi utiliser <code>FormData</code> avec jQuery si vous configurez les bonnes options :</p>
<pre class="brush: js">var fd = new FormData(document.getElementById("fileinfo"));
fd.append("CustomField", "This is some extra data");
$.ajax({
url: "stash.php",
type: "POST",
data: fd,
processData: false, // indique à jQuery de ne pas traiter les données
contentType: false // indique à jQuery de ne pas configurer le contentType
});
</pre>
<h2 id="Soumettre_des_formulaires_et_téléverser_des_fichiers_via_AJAX_sans_objets_FormData">Soumettre des formulaires et téléverser des fichiers via AJAX <em>sans</em> <code>objets FormData</code></h2>
<p>Si vous souhaitez savoir comment sérialiser et soumettre via <a href="/en-US/docs/AJAX" title="/en-US/docs/AJAX">AJAX</a> un formulaire<em> sans</em> utiliser d'objets FormData, veuillez consulter <a href="/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest#Submitting_forms_and_uploading_files" title="/en-US/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest#Submitting_forms_and_uploading_files">ce paragraphe</a>.</p>
<h2 id="Voir_aussi">Voir aussi</h2>
<ul>
<li><a href="/en-US/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest" title="/en-US/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest">Using XMLHttpRequest</a></li>
<li><a href="/en-US/docs/DOM/HTMLFormElement" title="/en-US/docs/DOM/HTMLFormElement"><code>HTMLFormElement</code></a></li>
<li><a href="/en-US/docs/DOM/Blob" title="/en-US/docs/DOM/Blob"><code>Blob</code></a></li>
<li><a href="/en-US/docs/JavaScript/Typed_arrays" title="/en-US/docs/JavaScript/Typed_arrays">Typed Arrays</a></li>
</ul>
|
