Utiliser XMLHttpRequest - Les API Web | MDN

Basculer la barre latérale

Thème

Automatique
Clair
Sombre

Français

Se souvenir de la langue En savoir plus

Utiliser XMLHttpRequest

Baseline Large disponibilité *

Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis juillet 2015.

* Certaines parties de cette fonctionnalité peuvent bénéficier de prise en charge variables.

Dans ce guide, nous verrons comment utiliser XMLHttpRequest afin d'envoyer des requêtes HTTP pour échanger des données entre le site web et un serveur.

Des exemples d'utilisation seront présentés.

Pour envoyer une requête HTTP, on pourra :

Créer un objet XMLHttpRequest
Ouvrir une URL
Envoyer la requête

Lorsque la transaction sera terminée, l'objet XMLHttpRequest contiendra les informations de la réponse, comme son corps et le statut HTTP résultant.

js
function reqListener() {
  console.log(this.responseText);
}

const req = new XMLHttpRequest();
req.addEventListener("load", reqListener);
req.open("GET", "http://www.example.org/example.txt");
req.send();

Dans cet article

Types de requêtes

Une requête envoyée avec XMLHttpRequest peut récupérer les données de façon asynchrone ou de façon synchrone. Le comportement obtenu est choisi avec le troisième argument optionnel async de la méthode XMLHttpRequest.open(). Lorsque cet argument vaut true ou s'il n'est pas fourni, la requête est traitée de façon asynchrone. Sinon, le processus est géré de façon synchrone. Pour en savoir plus sur ces différents types de requêtes, vous pouvez consulter l'article Requêtes synchrones et asynchrones. Les requêtes synchrones ne peuvent pas être utilisées en dehors des workers, car elles bloqueraient l'interface principale.

Note : Le constructeur XMLHttpRequest ne se limite pas aux seuls documents XML. Son nom commence par "XML", car il a été créé lorsque le format d'échange principal était XML.

Gérer les réponses

Il existe plusieurs types d'attributs de réponse définis pour le constructeur XMLHttpRequest(). Ces attributs indiquent au client qui a émis la requête des informations importantes quant au statut de la réponse. Pour les cas où il faut gérer une réponse qui n'est pas du texte, cela peut nécessiter des manipulations et une analyse que nous allons voir dans les sections suivantes.

Analyser et manipuler la propriété responseXML

Lorsqu'on utilise XMLHttpRequest pour obtenir le contenu d'un document XML distant, la propriété responseXML sera un objet DOM qui contient le document XML analysé. La manipulation et l'analyse d'un tel résultat n'est pas nécessairement simple. Il existe quatre méthodes principales pour analyser un tel document XML :

Utiliser XPath afin de cibler certains emplacements du document.
Analyser et sérialiser manuellement le XML afin d'obtenir des chaînes de caractères ou des objets.
Utiliser XMLSerializer afin de sérialiser des arbres DOM en chaînes de caractères ou en fichiers.
Les expressions rationnelles peuvent être utilisées pour scanner le document si on ne connaît pas son contenu au préalable. On peut ainsi retirer les sauts de ligne par exemple. Attention, cette méthode n'est à utiliser qu'en dernier recours, car si le code XML change légèrement, il faudra revoir la méthode.

Note : XMLHttpRequest peut également interpréter un document HTML avec la propriété responseXML. Voir l'article à propos de la prise en charge de HTML dans XMLHttpRequest pour apprendre comment faire.

Traiter une propriété responseText contenant un document HTML

Lorsqu'on utilise XMLHttpRequest afin d'obtenir le contenu d'une page HTML distante, la propriété responseText sera une chaîne de caractères contenant le document HTML brut. La manipulation et l'analyse d'un tel résultat n'est pas nécessairement simple. Il existe trois méthodes principales pour analyser un tel document HTML :

Utiliser la propriété XMLHttpRequest.responseXML comme indiqué dans l'article Prise en charge de HTML dans XMLHttpRequest.
Injecter le contenu dans le corps d'un fragment de document à l'aide de fragment.body.innerHTML et traverser le DOM de ce fragment.
Les expressions rationnelles peuvent être utilisées pour scanner le document si on ne connaît pas son contenu au préalable. On peut ainsi retirer les sauts de ligne par exemple. Attention, cette méthode n'est à utiliser qu'en dernier recours, car si le code HTML change légèrement, il faudra revoir la méthode.

Gérer les données binaires

Bien que XMLHttpRequest soit généralement afin d'envoyer et de recevoir des données texte, on peut aussi l'utiliser pour envoyer et recevoir des données binaires. Il existe plusieurs méthodes pour ce faire, qui utilisent la méthode overrideMimeType() :

js
const req = new XMLHttpRequest();
req.open("GET", url);
// On récupère les données non-traitées comme une chaîne binaire
req.overrideMimeType("text/plain; charset=x-user-defined");
/* … */

D'autres techniques plus modernes existent également. En effet responseType prend en charge plusieurs types de contenu, permettant ainsi d'envoyer et de recevoir des données binaires plus facilement.

Prenons le fragment de code qui suit, qui utilise responseType avec "arraybuffer" afin de récupérer le contenu distant dans un objet ArrayBuffer qui stocke les données binaires.

js
const req = new XMLHttpRequest();

req.onload = (e) => {
  const arraybuffer = req.response; // pas responseText
  /* … */
};
req.open("GET", url);
req.responseType = "arraybuffer";
req.send();

Pour plus d'exemples, voir la page Envoyer et recevoir des données binaires.

Connaître l'avancement

XMLHttpRequest permet d'écouter différents évènements qui se produisent lors du traitement de la requête. Parmi ces évènements, on trouve de quoi notifier l'avancement, les erreurs, etc.

Pour suivre l'évolution d'un transfert avec XMLHttpRequest, on utilisera progress qui implémente l'interface ProgressEvent. Les évènements qui peuvent être écoutés pour connaître l'avancement de la requête sont :

progress

La quantité de données reçues a changé.

load

Le transfert est terminé. Toutes les données sont désormais écrites dans response.

js
const req = new XMLHttpRequest();

req.addEventListener("progress", updateProgress);
req.addEventListener("load", transferComplete);
req.addEventListener("error", transferFailed);
req.addEventListener("abort", transferCanceled);

req.open();

// …

// Avancement du transfert du serveur au client (téléchargements)
function updateProgress(event) {
  if (event.lengthComputable) {
    const percentComplete = (event.loaded / event.total) * 100;
    // …
  } else {
    // Impossible de connaître l'avancement, car la taille
    // totale est inconnue
  }
}

function transferComplete(evt) {
  console.log("Le transfert est terminé.");
}

function transferFailed(evt) {
  console.log("Une erreur est survenue lors du transfert du fichier.");
}

function transferCanceled(evt) {
  console.log("Le transfert a été annulé.");
}

Les lignes 3 à 6 du fragment ci-avant ajoutent les gestionnaires d'évènements pour les différents évènements émis à propos du transfert des données à l'aide de XMLHttpRequest.

Note : Ces gestionnaires d'évènements doivent être ajoutés avant d'appeler open() sur la requête. Sinon, les évènements progress ne seront pas captés.

Le gestionnaire d'évènement pour l'avancement, porté par la fonction updateProgress() dans l'exemple, reçoit le nombre total d'octets à transférer (total) ainsi que le nombre d'octets transférés jusqu'à présent (loaded). Toutefois, si le champ lengthComputable vaut false, la longueur totale est inconnue et vaudra 0 par défaut.

Les évènements d'avancement existent pour les téléchargements (downloads) et les téléversements (uploads). Pour les téléchargements, les évènements sont déclenchés sur l'objet XMLHttpRequest, comme illustré dans l'exemple précédent. Pour les téléversements, les évènements sont déclenchés sur l'objet XMLHttpRequest.upload, comme ceci :

js
const req = new XMLHttpRequest();

req.upload.addEventListener("progress", updateProgress);
req.upload.addEventListener("load", transferComplete);
req.upload.addEventListener("error", transferFailed);
req.upload.addEventListener("abort", transferCanceled);

oReq.open();

Note : Les évènements d'avancement ne sont pas disponibles pour le protocole file:.

Les évènements d'avancements sont émis à chaque fragment (chunk) de données reçu, y compris le dernier fragment pour les cas où le paquet est reçu et la connexion fermée avant que l'évènement soit déclenché. Dans ce cas, l'évènement progress est automatiquement déclenché lorsque l'évènement load se produit pour ce paquet. Cela permet de surveiller l'avancement de façon fiable, à l'aide du seul évènement progress.

On peut également détecter les trois conditions de fin de chargement (abort, load, ou error) à l'aide de l'évènement loadend :

js
req.addEventListener("loadend", loadEnd);

function loadEnd(e) {
  console.log(
    "Le transfert est terminé (mais on ne sait pas s'il a réussi ou non).",
  );
}

Il n'y a pas de certitude possible quant à l'information reçue par l'évènement loadend pour déterminer la condition de l'arrêt. Toutefois, cet évènement permet de gérer les tâches nécessaires à la fin des transferts.

Obtenir la date de dernière modification

js
function getHeaderTime() {
  console.log(this.getResponseHeader("Last-Modified")); // Une date GMTString valide ou null
}

const req = new XMLHttpRequest();
req.open(
  "HEAD", // On utilise HEAD, car on ne veut récupérer que les en-têtes
  "votrepage.html",
);
req.onload = getHeaderTime;
req.send();

Réaliser une action lorsque la date de dernière modification change

Créons deux fonctions :

js
function getHeaderTime() {
  const lastVisit = parseFloat(
    window.localStorage.getItem(`lm_${this.filepath}`),
  );
  const lastModified = Date.parse(this.getResponseHeader("Last-Modified"));

  if (isNaN(lastVisit) || lastModified > lastVisit) {
    window.localStorage.setItem(`lm_${this.filepath}`, Date.now());
    isFinite(lastVisit) && this.callback(lastModified, lastVisit);
  }
}

function ifHasChanged(URL, callback) {
  const req = new XMLHttpRequest();
  req.open(
    "HEAD" /* On utilise HEAD, car on ne veut récupérer que les en-têtes */,
    URL,
  );
  req.callback = callback;
  req.filepath = URL;
  req.onload = getHeaderTime;
  req.send();
}

Pour tester cet exemple :

js
// Testons le fichier "votrepage.html"
ifHasChanged("votrepage.html", function (modified, visit) {
  console.log(
    `La page '${this.filepath}' a été modifiée le ${new Date(
      nModified,
    ).toLocaleString()}!`,
  );
});

Si vous souhaitez savoir si la page actuelle a changé, voyez l'article document.lastModified.

Utiliser XMLHttpRequest entre différentes origines

Les navigateurs prennent en charge les requêtes entre différents sites/origines en implémentant le standard CORS (Cross-Origin Resource Sharing (pour « partage des ressources entre différentes origines »). Tant que le serveur est configuré afin d'autoriser les requêtes depuis l'origine de votre application web, XMLHttpRequest fonctionnera correctement. Dans le cas contraire, une exception INVALID_ACCESS_ERR sera déclenchée.

Outrepasser le cache

Pour outrepasser le cache avec une méthode qui fonctionne dans les différents navigateurs, on pourra ajouter un horodatage à l'URL en s'assurant d'encoder correctement la valeur (avec ? ou & où c'est nécessaire). Ainsi :

http://example.com/truc.html -> http://example.com/truc.html?12345 http://example.com/truc.html?bidule=machin -> http://example.com/truc.html?bidule=machin&12345

Le cache local étant indexé avec les URL, chaque requête sera ainsi unique et passera outre le cache.

On peut ajuster les URL automatiquement avec le code qui suit :

js
const req = new XMLHttpRequest();

req.open("GET", url + (/\?/.test(url) ? "&" : "?") + new Date().getTime());
req.send(null);

Securité

La méthode recommandée pour autoriser les requêtes scriptées entre différentes origines est d'inclure l'en-tête HTTP Access-Control-Allow-Origin dans la réponse à la requête XHR.

Interruptions des requêtes XHR

Si votre requête XHR se termine avec status=0 et statusText=null, cela signifie que son exécution n'a pas été autorisée. Elle n'a pas été envoyée (UNSENT). Cela se produit généralement lorsque l'origine de la requête a changé entre la création et l'ouverture qui suit avec open(). Cela peut par exemple se produire lorsqu'une requête XHR est déclenchée pour un évènement onunload d'une fenêtre. La requête est créée lorsque la fenêtre à fermer existe encore, mais l'envoi qui suit (avec open()) se produit lorsque la fenêtre a perdu le focus et l'a passé à une autre fenêtre. Pour éviter ce problème, le mieux consistera à placer un gestionnaire d'évènements DOMActivate sur la nouvelle fenêtre lorsque la fenêtre à fermer reçoit l'évènement unload.

Aider à améliorer MDN

Cette page vous a-t-elle été utile ?

Oui Non

Apprendre à contribuer

Cette page a été modifiée le 9 oct. 2025 par les contributeur·ice·s du MDN.

Voir cette page sur GitHub • Signaler un problème avec ce contenu