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 avant`send()`.

### 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 with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

* `XMLSerializer` : sérialiser un arbre DOM en XML
* Les tutoriels MDN sur `XMLHttpRequest`:
    + Introduction à AJAX
    + Utiliser XMLHttpRequest
    + Manipuler le HTML avec XMLHttpRequest (en-US)
    + L'API Fetch
* HTML5 Rocks — Nouvelles astuces avec XMLHttpRequest2 (en anglais)