XMLHttpRequest

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.

Note: Les versions de Firefox antérieures à la version 3 envoient toujours la requête à l'aide de l'encodage UTF-8 ; Firefox 3 envoie correctement le document à l'aide de l'encodage spécifié par data.xmlEncoding, ou en UTF-8 si aucun encodage n'est spécifié.

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 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.

Note : Firefox 3 vérifie correctement que les valeurs des champs target, currentTarget et this de l'objet event référencent les bons objets lors de l'appel de gestionnaires d'évènements pour des documents XML représentés par XMLDocument. Consultez le bug 198595 pour des détails.

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.
Au lieu de faire :

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

Faites plutôt 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);

Nombre limité de connexions XMLHttpRequest simultanées

La préférence network.http.max-persistent-connections-per-server dans about:config limite le nombre de connexions à 2 par défaut. Certaines pages interactives utilisant XMLHttpRequest peuvent maintenir une connexion ouverte. L'ouverture de deux ou trois de ces pages dans différents onglets ou fenêtres peut provoquer un blocage du navigateur de sorte que la fenêtre n'est plus redessinée et les contrôles ne répondent plus.

Requêtes inter-sites

Les requêtes XMLHttpRequest inter-sites Nouveau dans Firefox 3 sont disponibles en utilisant le brouillon de travail de la spécification W3C Access Control. Deux différentes manières d'utiliser cette fonctionnalité existent. La première est d'ajouter un nouvel en-tête Access-Control, qui peut être utilisé pour tous les types de ressources et lorsque vous avez un plus grand niveau de contrôle sur le serveur web. La seconde est une instruction de traitement access-control, qui n'est utile que pour les documents XML. Vous trouverez plus d'informations dans le document Requêtes XMLHttpRequest inter-sites.

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