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 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 appelé lorsque la requête a expiré.

XMLHttpRequest.upload (en-US) Lecture seule

Un objet XMLHttpRequestUpload (en-US) 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 Obsolète Lecture seule

Un objet ArrayBuffer qui est la réponse à la requête sous la forme d'un tableau typé JavaScript.

XMLHttpRequest.multipart Obsolète

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() Obsolète

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 (en-US) est également disponible.

loadend

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

Specification
XMLHttpRequest Standard
# interface-xmlhttprequest

Compatibilité des navigateurs

BCD tables only load in the browser

Voir aussi