XMLHttpRequest

Les objets XMLHttpRequest (XHR) permettent d'interagir avec des serveurs. On peut récupérer des données à partir d'une URL sans avoir à rafraîchir complètement la page. Cela permet à une page web d'être mise à jour sans perturber les actions de l'utilisateur. XMLHttpRequest est beaucoup utilisé par l'approche AJAX.

Malgré son nom, XMLHttpRequest peut être utilisé afin de récupérer tout type de données et pas uniquement du XML.

Si vos opérations de communication nécessitent l'échange d'évènements ou de messages avec un serveur, pensez à utiliser les évènements serveur via l'interface EventSource. Pour une communication bidirectionnelle complète, les WebSockets peuvent être une meilleure alternative.

Constructeur

XMLHttpRequest()
Le constructeur initialise un objet XMLHttpRequest. Il doit être appelé avant toute autre méthode.

Propriétés

Cette interface hérite également des propriétés de XMLHttpRequestEventTarget et de EventTarget.

XMLHttpRequest.onreadystatechange
Un gestionnaire d'évènement (event handler) invoqué à chaque fois que l'attribut readyState change.
XMLHttpRequest.readyState Lecture seule
L'état de la requête sous la forme d'un unsigned short.
XMLHttpRequest.response Lecture seule
Un objet ArrayBuffer, Blob, Document, un objet JavaScript ou une chaîne de caractères (DOMString) selon la valeur de XMLHttpRequest.responseType (en-US). Cet objet contient le corps de la réponse.
XMLHttpRequest.responseText Lecture seule
Une chaîne de caractères DOMString qui contient la réponse à la requête sous forme de texte ou la valeur null si la requête a échoué ou n'a pas encore été envoyée.
XMLHttpRequest.responseType (en-US)
Une valeur parmi une liste qui définit le type de réponse.
XMLHttpRequest.responseURL (en-US) Lecture seule
L'URL sérialisée de la réponse ou la chaîne vide si l'URL est nulle.
XMLHttpRequest.responseXML (en-US) Lecture seule
Un objet Document qui contient la réponse de la requête ou null si la requête a échoué, qu'elle n'a pas encore été envoyée ou qu'elle ne peut pas être analysée comme XML ou HTML. Cette propriété n'est pas disponible dans les workers.
XMLHttpRequest.status Lecture seule
Une valeur numérique unsigned short qui décrit le statut de la réponse à la requête.
XMLHttpRequest.statusText (en-US) Lecture seule
Une chaîne DOMString qui contient la chaîne de caractères / réponse renvoyée par le serveur HTTP. À la différence de XMLHttpRequest.status, tout le texte du statut est inclus ("200 OK" plutôt que "200" par exemple).

Note : Selon la spécification HTTP/2 (voir 8.1.2.4 Response Pseudo-Header Fields), HTTP/2 ne définit pas de méthode pour porter la version ou la raison/phrase incluse dans la ligne de statut HTTP/1.1.

XMLHttpRequest.timeout
Un entier unsigned long qui représente le nombre de millisecondes qu'une requête peut prendre avant d'être terminée automatiquement.
XMLHttpRequestEventTarget.ontimeout
Un gestionnaire d'évènement (event handler) appelé lorsque la requête a expiré.
XMLHttpRequest.upload (en-US) Lecture seule
Un objet XMLHttpRequestUpload qui représente le processus d'upload.
XMLHttpRequest.withCredentials
Un booléen (Boolean (en-US)) qui indique si des requêtes Access-Control d'origines différentes peuvent être effectuées avec des informations d'authentification telles que des cookies ou des en-têtes d'autorisation.

Propriétés non-standard

XMLHttpRequest.channel (en-US)Lecture seule
Un objet nsIChannel. Le canal à utiliser par l'objet lorsqu'il effectue la requête.
XMLHttpRequest.mozAnon (en-US)Lecture seule
Un booléen. S'il est vrai, la requête sera envoyée sans cookie ou en-tête d'autorisation.
XMLHttpRequest.mozSystem (en-US)Lecture seule
Un booléen. S'il est vrai, la politique d'origine unique ne sera pas vérifiée pour la requête.
XMLHttpRequest.mozBackgroundRequest (en-US)
Un booléen qui indique si l'objet représente une requête de service en arrière-plan.
XMLHttpRequest.mozResponseArrayBuffer (en-US) Obsolète depuis Gecko 6 Lecture seule
Un objet ArrayBuffer qui est la réponse à la requête sous la forme d'un tableau typé JavaScript.
XMLHttpRequest.multipart (en-US)Obsolète depuis Gecko 22
Cette fonctionnalité spécifique à Gecko a été retirée avec Firefox/Gecko 22. Veuillez utiliser les évènements serveurs ou les web sockets ou encore la propriété responseText des évènements de progression.

Gestionnaires d'évènement

Le gestionnaire onreadystatechange, comme propriété des instances XMLHttpRequest, est pris en charge par l'ensemble des navigateurs.

D'autres gestionnaires d'évènements ont également été implémentés dans différents navigateurs (onload, onerror, onprogress, etc.). Voir le guide Manipuler XMLHttpRequest.

La plupart des navigateurs récents gère également les évènements via la méthode addEventListener() (en plus des méthodes  on*).

Méthodes

XMLHttpRequest.abort() (en-US)
Interrompt la requête si elle a déjà été envoyée.
XMLHttpRequest.getAllResponseHeaders() (en-US)
Renvoie, via une chaîne de caractères, l'ensemble des en-têtes de la réponse, séparés par CRLF ou la valeur null si aucune réponse n'a été reçue.
XMLHttpRequest.getResponseHeader() (en-US)
Renvoie la chaîne de caractères contenant le texte de l'en-tête voulue ou null si aucune des réponse n'a été reçue ou si l'en-tête n'existe pas dans la réponse.
XMLHttpRequest.open()
Initialise une requête. Cette méthode doit être utilisée par du code JavaScript.
XMLHttpRequest.overrideMimeType() (en-US)
Surcharge le type MIME renvoyé par le serveur.
XMLHttpRequest.send()
Envoie la requête. Si la requête est asynchrone (le comportement par défaut), la méthode renvoie un résultat dès que la requête est envoyée.
XMLHttpRequest.setRequestHeader()
Définit la valeur d'un en-tête de requête HTTP. Cette méthode doit être appelée après open() mais avantsend().

Méthodes non-standard

XMLHttpRequest.init()
Initialise l'objet depuis pour une utilisation depuis du code C++.
Attention ! Cette méthode ne doit pas être appelée depuis du code JavaScript.
XMLHttpRequest.openRequest()
Initialise une requête depuis du code natif. Voir la méthode open() ci-avant pour initialiser une requête de façon standard en JavaSCript.
XMLHttpRequest.sendAsBinary()
Une variante de send() afin d'envoyer des données binaires.

Évènements

abort
Se déclenche lorsqu'une requête a été interrompue (par exemple via XMLHttpRequest.abort() (en-US)). Le gestionnaire
onabort (en-US) est également disponible.
error (en-US)
Se déclenche lorsqu'une requête a rencontré une erreur.
Le gestionnaire onerror (en-US) est également disponible.
load (en-US)
Se déclenche lorsqu'une transaction XMLHttpRequest se termine correctement. Le gestionnaire onload est également disponible.
loadend (en-US)
Se déclenche lorsqu'une requête est terminée (avec une erreur ou non). Quand elle a réussi, l'évènement a lieu après load (en-US)). Quand elle a échoué, l'évènement survient après error (en-US)).
Le gestionnaire onloadend est également disponible.
loadstart (en-US)
Se déclenche lorsqu'une requête commence à charger des données.
Le gestionnaire onloadstart (en-US) est également disponible.
progress (en-US)
Se déclenche périodiquement lorsqu'une requête reçoit des données supplémentaires. Le gestionnaire onprogress (en-US) est également disponible.
timeout (en-US)
Se déclenche lorsque la progression est terminée du fait de l'expiration de la durée limite. Le gestionnaire ontimeout est également disponible.

Spécifications

Spécification État Commentaires
XMLHttpRequest Standard évolutif Standard évolutif, version la plus récente.

Compatibilité des navigateurs

BCD tables only load in the browser

Voir aussi