Utiliser XMLHttpRequest

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.

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.

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 :

1. Utiliser XPath afin de cibler certains emplacements du document.
2. Analyser et sérialiser manuellement le XML afin d'obtenir des chaînes de caractères ou des objets.
3. Utiliser XMLSerializer afin de sérialiser des arbres DOM en chaînes de caractères ou en fichiers.
4. 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.

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 :

1. Utiliser la propriété XMLHttpRequest.responseXML comme indiqué dans l'article Prise en charge de HTML dans XMLHttpRequest.
2. Injecter le contenu dans le corps d'un fragment de document à l'aide de fragment.body.innerHTML et traverser le DOM de ce fragment.
3. 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.

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

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.

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.

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.

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.

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 :

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

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 :

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.

Créons deux fonctions :

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 :

// 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.

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.

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 :

const req = new XMLHttpRequest();

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

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.

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.

• Utiliser l'API Fetch
• Prise en charge de HTML dans XMLHttpRequest
• Contrôle d'accès HTTP (CORS)
• Spécification WHATWG pour l'objet XMLHttpRequest