MDN wants to talk to developers like you: https://qsurvey.mozilla.com/s3/8d22564490d8

 

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 (synchrone)

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, une fois la requête terminé.

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

// Ici, la requête sera émise de façon synchrone.
const req = new XMLHttpRequest();
req.open('GET', 'http://www.mozilla.org/', false); 
req.send(null);

if (req.status === 200) {
    console.log("Réponse reçu: %s", req.responseText);
} else {
    console.log("Status de la réponse: %d (%s)", req.status, req.statusText);
}

Note : Cet exemple fonctionne de manière 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

const req = new XMLHttpRequest();
req.open('GET', 'file:///home/user/file.json', false);
req.send(null);

// if (req.status === 0) {}

console.log(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

Lors d'une requête HTTP, son état va varier, et nous pouvons récupérer chaque changement de cet état, avec l'événement onreadystatechange .
Il y a 5 états:

Code État Description
0 UNSENT L'objet est prêt, mais la méthode open() n'a pas encore été appelé.
1 OPENED open() à été appelé.
2 HEADERS_RECEIVED send() à été appelé, les headers et status sont disponibles au sein de l'objet.
3 LOADING Réception en cours, les données reçues sont partielles.
4 DONE La requête est terminée.

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

const req = new XMLHttpRequest();

req.onreadystatechange = function(event) {
    // XMLHttpRequest.DONE === 4
    if (this.readyState === XMLHttpRequest.DONE) {
        if (this.status === 200) {
            console.log("Réponse reçu: %s", this.responseText);
        } else {
            console.log("Status de la réponse: %d (%s)", this.status, this.statusText);
        }
    }
};

req.open('GET', 'http://www.mozilla.org/', true);
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(event) {
    if (event.lengthComputable) {
        var percentComplete = (event.loaded / event.total)*100;
        console.log("Téléchargement: %d%%", percentComplete);
    } else {
        // Impossible de calculer la progression puisque la taille totale est inconnue
    }
}

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

function onLoad(event) {
    // Ici, this.readyState égale XMLHttpRequest.DONE .
    if (this.status === 200) {
        console.log("Réponse reçu: %s", this.responseText);
    } else {
        console.log("Status de la réponse: %d (%s)", this.status, this.statusText);
    }
}

function onLoadEnd(event) {
    // Cet événement est exécuté, une fois la requête terminée.
    console.log("Le transfert est terminé. (peut importe le résultat)");
}

const req = new XMLHttpRequest();
req.onprogress = onProgress;
req.onerror = onError;
req.onload = onLoad;
req.onloadend = onLoadEnd;

req.open('GET', 'http://www.mozilla.org/', true);
req.send(null);

Les attributs de l'évènement onprogress, loaded et total, 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().
const 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 HTTP sur la requête avant de l'envoyer.

Note : Vous devez appeler open() avant d'appeler cette méthode.
const 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.

const req = new XMLHttpRequest();
req.open('GET', 'http://www.mozilla.org/', true);
req.send(null);

console.log("Content-Type: %s", req.getResponseHeader("Content-Type"));

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 :

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

Faites plutôt ceci :

const 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érencenetwork.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 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

Voir aussi

 

Étiquettes et contributeurs liés au document

Étiquettes : 
 Dernière mise à jour par : lessonsharing,