XMLHttpRequest

  • Raccourci de la révision : XMLHttpRequest
  • Titre de la révision : XMLHttpRequest
  • ID de la révision : 170655
  • Créé :
  • Créateur : BenoitL
  • Version actuelle ? Non
  • Commentaire mise à jour

Contenu de la révision

XMLHttpRequest est un objet JavaScript qui a été créé par Microsoft et adopté par Mozilla. Vous pouvez l'utiliser pour récupérer facilement des données via HTTP. En dépit de son nom, il a d'autres usages que de seuls documents XML. Dans Gecko, cet objet implémente les interfaces nsIJSXMLHttpRequest et nsIXMLHttpRequest. Les versions récentes de Gecko ont fait subir quelques modifications à cet objet (voir Changements dans XMLHttpRequest pour Gecko 1.8).

Utilisation basique

L'utilisation de XMLHttpRequest est très simple. Il vous suffit de créer une instance de cet objet, d'ouvrir une URL et d'envoyer la requête. Le code d'état HTTP de la réponse, ainsi que le document résultant sont disponibles dans cet objet après la requête.

Exemple

var req = new XMLHttpRequest();
req.open('GET', 'http://www.mozilla.org/', false); 
req.send(null);
if(req.status == 200)
  dump(req.responseText);
Note : Cet exemple fonctionne de façon synchrone, donc il va bloquer l'interface utilisateur lorsque vous l'appellerez depuis JavaScript. Il est déconseillé en pratique de procéder ainsi.

Exemple avec un autre protocole que http

var req = new XMLHttpRequest();
req.open('GET', 'file:///home/user/file.json', false);
req.send(null);
if(req.status == 0)
  dump(req.responseText);
Note : les protocoles file:/// et ftp:// ne renvoient pas d'état HTTP, c'est pourquoi les requêtes renvoient zéro pour status et une chaîne vide pour statusText. Consultez le {{template.Bug(331610)}} pour plus de détails.

Utilisation asynchrone

Si vous avez l'intention d'utiliser XMLHttpRequest dans une extension, vous devriez vous arranger pour que ses requêtes soient asynchrones. En utilisation asynchrone, vous disposez d'une fonction d'appel en retour lorsque les données ont été reçues, ce qui permet au navigateur de continuer à fonctionner normalement jusqu'à ce que la requête aboutisse.

Exemple

var req = new XMLHttpRequest();
req.open('GET', 'http://www.mozilla.org/', true);
req.onreadystatechange = function (aEvt) {
  if (req.readyState == 4) {
     if(req.status == 200)
      dump(req.responseText);
     else
      dump("Erreur pendant le chargement de la page.\n");
  }
};
req.send(null); 

Examen de la progression

XMLHttpRequest permet d'écouter divers évènements pouvant se produire au cours du traitement de la requête. Parmi ceux-ci, des notifications périodiques de la progression, des erreurs, et ainsi de suite.

Si, par exemple, vous désirez fournir à l'utilisateur des informations concernant la progression de la requête durant la réception d'un document, vous pouvez utiliser ce type de code :

function onProgress(e) {
  var percentComplete = (e.position / e.totalSize)*100;
  ...
}

function onError(e) {
  alert("Une erreur " + e.target.status + " s'est produite au cours de la réception du document.");
}

function onLoad(e) {
  // ...
}
// ...
var req = new XMLHttpRequest();
req.onprogress = onProgress;
req.open("GET", url, true);
req.onload = onLoad;
req.onerror = onError;
req.send(null);

Les attributs de l'évènement onprogress, position et totalSize, indiquent respectivement le nombre d'octets actuellement reçus et le nombre total d'octets attendus.

Tous ces évènements ont leur attribut target défini vers l'objet XMLHttpRequest auxquels ils correspondent.

Autres propriétés et méthodes

En complément de celles indiquées plus haut, d'autres propriétés et méthodes sont disponibles sur cet objet de requête.

responseXML

Si vous chargez un document XML, la propriété responseXML contiendra le document sous la forme d'un objet XmlDocument manipulables en utilisant les méthodes du DOM. Si le serveur transmet un XML bien formé mais sans préciser un entête Content-Type XML, vous pouvez utiliser overrideMimeType() pour forcer le document à être traité comme du XML. Si toutefois le serveur transmet un document XML mal formé, responseXML aura une valeur null quelque soit le remplacement de type mime appliqué.

overrideMimeType()

Cette méthode force un document à être traité selon un type de contenu particulier. On appelle cette méthode en général lors de l'utilisation de responseXML sur un serveur transmettant du XML avec un en-tête Content-Type incorrect.
Note : Cette méthode doit être appelée avant l'appel de send().
var req = new XMLHttpRequest();
req.open('GET', 'http://www.mozilla.org/', true);
req.overrideMimeType('text/xml');
req.send(null);

setRequestHeader()

Cette méthode sert à définir un entête HTPP sur la requête avant de l'envoyer.
Note : Vous devez appeler open() avant d'appeler cette méthode.
var req = new XMLHttpRequest();
req.open('GET', 'http://www.mozilla.org/', true);
req.setRequestHeader("X-Foo", "Bar");
req.send(null);

getResponseHeader()

Cette méthode permet d'obtenir un entête HTTP à partir de la réponse du serveur.

var req = new XMLHttpRequest();
req.open('GET', 'http://www.mozilla.org/', true);
req.send(null);
dump("Content-Type: " + req.getResponseHeader("Content-Type") + "\n");

Utilisation depuis des composants XPCOM

Note : des modifications sont nécessaires si vous utilisez XMLHttpRequest depuis un composant XPCOM JavaScript.

XMLHttpRequest ne peut pas être instancié à l'aide du constructeur XMLHttpRequest() depuis un composant XPCOM JavaScript. Le constructeur n'est pas défini à l'intérieur des composants et le code produira une erreur. Il sera alors nécessaire de le créer et de l'utiliser avec une autre syntaxe.

Plutôt que de faire :

var req = new XMLHttpRequest();
req.onprogress = onProgress;
req.onload = onLoad;
req.onerror = onError;
req.open("GET", url, true);
req.send(null);

Faites ceci:

var request = Components.
              classes["@mozilla.org/xmlextras/xmlhttprequest;1"].
              createInstance();

// Interrogez l'interface nsIDOMEventTarget de l'objet pour lui ajouter des gestionnaires d'évènement :

request.QueryInterface(Components.interfaces.nsIDOMEventTarget);
request.addEventListener("progress", function(evt) { ... }, false);
request.addEventListener("load", function(evt) { ... }, false);
request.addEventListener("error", function(evt) { ... }, false);

// Interrogez l'interface nsIXMLHttpRequest pour ouvrir et envoyer la requête :

request.QueryInterface(Components.interfaces.nsIXMLHttpRequest);
request.open("GET", "http://www.example.com/", true);
request.send(null);


Références

  1. XMLHttpRequest - REST and the Rich User Experience
  2. Documentation XULPlanet
  3. Documentation Microsoft
  4. Référence des développeurs Apple
  5. "Using the XMLHttpRequest Object" (jibbering.com)
  6. The XMLHttpRequest Object : brouillon de travail du W3C
  7. Exemples avec multipart sur xulfr.org
{{ wiki.languages( { "en": "en/XMLHttpRequest", "es": "es/XMLHttpRequest", "it": "it/XMLHttpRequest", "ja": "ja/XMLHttpRequest", "ko": "ko/XMLHttpRequest", "pl": "pl/XMLHttpRequest" } ) }}

Source de la révision

<p>
</p><p><code>XMLHttpRequest</code> est un objet <a href="fr/JavaScript">JavaScript</a> qui a été créé par Microsoft et adopté par Mozilla. Vous pouvez l'utiliser pour récupérer facilement des données via HTTP. En dépit de son nom, il a d'autres usages que de seuls documents XML. Dans Gecko, cet objet implémente les interfaces <code><a href="fr/NsIJSXMLHttpRequest">nsIJSXMLHttpRequest</a></code> et <code><a href="fr/NsIXMLHttpRequest">nsIXMLHttpRequest</a></code>. Les versions récentes de Gecko ont fait subir quelques modifications à cet objet (voir <a href="fr/Changements_dans_XMLHttpRequest_pour_Gecko_1.8">Changements dans XMLHttpRequest pour Gecko 1.8</a>).
</p>
<h3 name="Utilisation_basique">Utilisation basique</h3>
<p>L'utilisation de <code>XMLHttpRequest</code> est très simple. Il vous suffit de créer une instance de cet objet, d'ouvrir une URL et d'envoyer la requête. Le code d'état HTTP de la réponse, ainsi que le document résultant sont disponibles dans cet objet après la requête.
</p>
<h4 name="Exemple">Exemple</h4>
<pre>var req = new XMLHttpRequest();
req.open('GET', 'http://www.mozilla.org/', false); 
req.send(null);
if(req.status == 200)
  dump(req.responseText);
</pre>
<div class="note"><b>Note :</b> Cet exemple fonctionne de façon synchrone, donc il va bloquer l'interface utilisateur lorsque vous l'appellerez depuis JavaScript. Il est déconseillé en pratique de procéder ainsi.</div>
<h4 name="Exemple_avec_un_autre_protocole_que_http"> Exemple avec un autre protocole que http </h4>
<pre>var req = new XMLHttpRequest();
req.open('GET', 'file:///home/user/file.json', false);
req.send(null);
if(req.status == 0)
  dump(req.responseText);
</pre>
<div class="note"><b>Note :</b> les protocoles file:/// et ftp:// ne renvoient pas d'état HTTP, c'est pourquoi les requêtes renvoient zéro pour <code>status</code> et une chaîne vide pour <code>statusText</code>. Consultez le {{template.Bug(331610)}} pour plus de détails.</div>
<h3 name="Utilisation_asynchrone">Utilisation asynchrone</h3>
<p>Si vous avez l'intention d'utiliser <code>XMLHttpRequest</code> dans une extension, vous devriez vous arranger pour que ses requêtes soient asynchrones. En utilisation asynchrone, vous disposez d'une fonction d'appel en retour lorsque les données ont été reçues, ce qui permet au navigateur de continuer à fonctionner normalement jusqu'à ce que la requête aboutisse.
</p>
<h4 name="Exemple_2">Exemple</h4>
<pre>var req = new XMLHttpRequest();
req.open('GET', 'http://www.mozilla.org/', true);
req.onreadystatechange = function (aEvt) {
  if (req.readyState == 4) {
     if(req.status == 200)
      dump(req.responseText);
     else
      dump("Erreur pendant le chargement de la page.\n");
  }
};
req.send(null); 
</pre>
<h4 name="Examen_de_la_progression">Examen de la progression</h4>
<p><code>XMLHttpRequest</code> permet d'écouter divers évènements pouvant se produire au cours du traitement de la requête. Parmi ceux-ci, des notifications périodiques de la progression, des erreurs, et ainsi de suite.
</p><p>Si, par exemple, vous désirez fournir à l'utilisateur des informations concernant la progression de la requête durant la réception d'un document, vous pouvez utiliser ce type de code :
</p>
<pre>function onProgress(e) {
  var percentComplete = (e.position / e.totalSize)*100;
  ...
}

function onError(e) {
  alert("Une erreur " + e.target.status + " s'est produite au cours de la réception du document.");
}

function onLoad(e) {
  // ...
}
// ...
var req = new XMLHttpRequest();
req.onprogress = onProgress;
req.open("GET", url, true);
req.onload = onLoad;
req.onerror = onError;
req.send(null);
</pre>
<p>Les attributs de l'évènement <code>onprogress</code>, <code>position</code> et <code>totalSize</code>, indiquent respectivement le nombre d'octets actuellement reçus et le nombre total d'octets attendus.
</p><p>Tous ces évènements ont leur attribut <code>target</code> défini vers l'objet <code>XMLHttpRequest</code> auxquels ils correspondent.
</p>
<h3 name="Autres_propri.C3.A9t.C3.A9s_et_m.C3.A9thodes">Autres propriétés et méthodes</h3>
<p>En complément de celles indiquées plus haut, d'autres propriétés et méthodes sont disponibles sur cet objet de requête.
</p>
<h4 name="responseXML">responseXML</h4>
<p>Si vous chargez un document <a href="fr/XML">XML</a>, la propriété <code>responseXML</code> contiendra le document sous la forme d'un objet <code>XmlDocument</code> manipulables en utilisant les méthodes du DOM. Si le serveur transmet un XML bien formé mais sans préciser un
entête Content-Type XML, vous pouvez utiliser <code><a href="fr/XMLHttpRequest#overrideMimeType.28.29">overrideMimeType()</a></code> pour forcer le document à être traité comme du XML. Si toutefois le serveur transmet un document XML mal formé, <code>responseXML</code> aura une valeur <code>null</code> quelque soit le remplacement de type mime appliqué.
</p>
<h4 name="overrideMimeType.28.29">overrideMimeType()</h4>
Cette méthode force un document à être traité selon un type de contenu particulier. On appelle cette méthode en général lors de l'utilisation de <code>responseXML</code> sur un serveur transmettant du <a href="fr/XML">XML</a> avec un en-tête Content-Type incorrect. <div class="note"><b>Note :</b> Cette méthode doit être appelée avant l'appel de <code>send()</code>.</div>
<pre>var req = new XMLHttpRequest();
req.open('GET', 'http://www.mozilla.org/', true);
req.overrideMimeType('text/xml');
req.send(null);
</pre>
<h4 name="setRequestHeader.28.29">setRequestHeader()</h4>
Cette méthode sert à définir un entête HTPP sur la requête avant de l'envoyer. <div class="note"><b>Note :</b> Vous devez appeler <code>open()</code> avant d'appeler cette méthode.</div>
<pre>var req = new XMLHttpRequest();
req.open('GET', 'http://www.mozilla.org/', true);
req.setRequestHeader("X-Foo", "Bar");
req.send(null);
</pre>
<h4 name="getResponseHeader.28.29">getResponseHeader()</h4>
<p>Cette méthode permet d'obtenir un entête HTTP à partir de la réponse du serveur.
</p>
<pre>var req = new XMLHttpRequest();
req.open('GET', 'http://www.mozilla.org/', true);
req.send(null);
dump("Content-Type: " + req.getResponseHeader("Content-Type") + "\n");
</pre>
<h3 name="Utilisation_depuis_des_composants_XPCOM"> Utilisation depuis des composants XPCOM </h3>
<div class="note"><b>Note :</b> des modifications sont nécessaires si vous utilisez XMLHttpRequest depuis un composant XPCOM JavaScript.</div>
<p>XMLHttpRequest ne peut pas être instancié à l'aide du constructeur <code>XMLHttpRequest()</code> depuis un composant XPCOM JavaScript. Le constructeur n'est pas défini à l'intérieur des composants et le code produira une erreur. Il sera alors nécessaire de le créer et de l'utiliser avec une autre syntaxe.
</p><p>Plutôt que de faire :
</p>
<pre>var req = new XMLHttpRequest();
req.onprogress = onProgress;
req.onload = onLoad;
req.onerror = onError;
req.open("GET", url, true);
req.send(null);
</pre>
<p>Faites ceci:
</p>
<pre>var request = Components.
              classes["@mozilla.org/xmlextras/xmlhttprequest;1"].
              createInstance();

// Interrogez l'interface nsIDOMEventTarget de l'objet pour lui ajouter des gestionnaires d'évènement :

request.QueryInterface(Components.interfaces.nsIDOMEventTarget);
request.addEventListener("progress", function(evt) { ... }, false);
request.addEventListener("load", function(evt) { ... }, false);
request.addEventListener("error", function(evt) { ... }, false);

// Interrogez l'interface nsIXMLHttpRequest pour ouvrir et envoyer la requête :

request.QueryInterface(Components.interfaces.nsIXMLHttpRequest);
request.open("GET", "http://www.example.com/", true);
request.send(null);
</pre>
<p><br>
</p>
<h3 name="R.C3.A9f.C3.A9rences">Références</h3>
<ol><li> <a class="external" href="http://www.peej.co.uk/articles/rich-user-experience.html">XMLHttpRequest - REST and the Rich User Experience</a>
</li><li> <a class="external" href="http://www.xulplanet.com/references/objref/XMLHttpRequest.html">Documentation XULPlanet</a>
</li><li> <a class="external" href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/xmlsdk/html/xmobjxmlhttprequest.asp">Documentation Microsoft</a>
</li><li> <a class="external" href="http://developer.apple.com/internet/webcontent/xmlhttpreq.html">Référence des développeurs Apple</a>
</li><li> <a class="external" href="http://jibbering.com/2002/4/httprequest.html">"Using the XMLHttpRequest Object" (jibbering.com)</a>
</li><li> <a class="external" href="http://www.w3.org/TR/XMLHttpRequest/">The XMLHttpRequest Object : brouillon de travail du W3C</a>
</li><li> <a class="external" href="http://xulfr.org/wiki/ApplisWeb/Request">Exemples avec multipart sur xulfr.org</a>
</li></ol>
{{ wiki.languages( { "en": "en/XMLHttpRequest", "es": "es/XMLHttpRequest", "it": "it/XMLHttpRequest", "ja": "ja/XMLHttpRequest", "ko": "ko/XMLHttpRequest", "pl": "pl/XMLHttpRequest" } ) }}
Revenir à cette révision