Utiliser XMLHttpRequest

Types de requtes

Une requte envoye avec XMLHttpRequest peut rcuprer les donnes de faon asynchrone ou de faon synchrone. Le comportement obtenu est choisi avec le troisime argument optionnel async de la mthode XMLHttpRequest.open(). Lorsque cet argument vaut true ou s'il n'est pas fourni, la requte est traite de faon asynchrone. Sinon, le processus est gr de faon synchrone. Pour en savoir plus sur ces diffrents types de requtes, vous pouvez consulter l'article Requtes synchrones et asynchrones. Les requtes synchrones ne peuvent pas tre utilises en dehors des workers, car elles bloqueraient l'interface principale.

Grer les rponses

Il existe plusieurs types d'attributs de rponse dfinis pour le constructeur XMLHttpRequest(). Ces attributs indiquent au client qui a mis la requte des informations importantes quant au statut de la rponse. Pour les cas o il faut grer une rponse qui n'est pas du texte, cela peut ncessiter des manipulations et une analyse que nous allons voir dans les sections suivantes.

Analyser et manipuler la proprit responseXML

Lorsqu'on utilise XMLHttpRequest pour obtenir le contenu d'un document XML distant, la proprit responseXML sera un objet DOM qui contient le document XML analys. La manipulation et l'analyse d'un tel rsultat n'est pas ncessairement simple. Il existe quatre mthodes principales pour analyser un tel document XML :

1. Utiliser XPath afin de cibler certains emplacements du document.
2. Analyser et srialiser manuellement le XML afin d'obtenir des chanes de caractres ou des objets.
3. Utiliser XMLSerializer afin de srialiser des arbres DOM en chanes de caractres ou en fichiers.
4. Les expressions rationnelles peuvent tre utilises pour scanner le document si on ne connat pas son contenu au pralable. On peut ainsi retirer les sauts de ligne par exemple. Attention, cette mthode n'est utiliser qu'en dernier recours, car si le code XML change lgrement, il faudra revoir la mthode.

Traiter une proprit responseText contenant un document HTML

Lorsqu'on utilise XMLHttpRequest afin d'obtenir le contenu d'une page HTML distante, la proprit responseText sera une chane de caractres contenant le document HTML brut. La manipulation et l'analyse d'un tel rsultat n'est pas ncessairement simple. Il existe trois mthodes principales pour analyser un tel document HTML :

1. Utiliser la proprit 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 utilises pour scanner le document si on ne connat pas son contenu au pralable. On peut ainsi retirer les sauts de ligne par exemple. Attention, cette mthode n'est utiliser qu'en dernier recours, car si le code HTML change lgrement, il faudra revoir la mthode.

Grer les donnes binaires

Bien que XMLHttpRequest soit gnralement afin d'envoyer et de recevoir des donnes texte, on peut aussi l'utiliser pour envoyer et recevoir des donnes binaires. Il existe plusieurs mthodes pour ce faire, qui utilisent la mthode overrideMimeType() :

const req = new XMLHttpRequest();
req.open("GET", url);
// On rcupre les donnes non-traites comme une chane 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 donnes binaires plus facilement.

Prenons le fragment de code qui suit, qui utilise responseType avec "arraybuffer" afin de rcuprer le contenu distant dans un objet ArrayBuffer qui stocke les donnes 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 donnes binaires.

Connatre l'avancement

XMLHttpRequest permet d'couter diffrents vnements qui se produisent lors du traitement de la requte. Parmi ces vnements, on trouve de quoi notifier l'avancement, les erreurs, etc.

Pour suivre l'volution d'un transfert avec XMLHttpRequest, on utilisera progress qui implmente l'interface ProgressEvent. Les vnements qui peuvent tre couts pour connatre l'avancement de la requte sont :

progress

La quantit de donnes reues a chang.

load

Le transfert est termin. Toutes les donnes sont dsormais 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 (tlchargements)
function updateProgress(event) {
  if (event.lengthComputable) {
    const percentComplete = (event.loaded / event.total) * 100;
    // 
  } else {
    // Impossible de connatre 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'vnements pour les diffrents vnements mis propos du transfert des donnes l'aide de XMLHttpRequest.

Le gestionnaire d'vnement pour l'avancement, port par la fonction updateProgress() dans l'exemple, reoit le nombre total d'octets transfrer (total) ainsi que le nombre d'octets transfrs jusqu' prsent (loaded). Toutefois, si le champ lengthComputable vaut false, la longueur totale est inconnue et vaudra 0 par dfaut.

Les vnements d'avancement existent pour les tlchargements (downloads) et les tlversements (uploads). Pour les tlchargements, les vnements sont dclenchs sur l'objet XMLHttpRequest, comme illustr dans l'exemple prcdent. Pour les tlversements, les vnements sont dclenchs 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 vnements d'avancements sont mis chaque fragment (chunk) de donnes reu, y compris le dernier fragment pour les cas o le paquet est reu et la connexion ferme avant que l'vnement soit dclench. Dans ce cas, l'vnement progress est automatiquement dclench lorsque l'vnement load se produit pour ce paquet. Cela permet de surveiller l'avancement de faon fiable, l'aide du seul vnement progress.

On peut galement dtecter les trois conditions de fin de chargement (abort, load, ou error) l'aide de l'vnement loadend :

req.addEventListener("loadend", loadEnd);

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

Il n'y a pas de certitude possible quant l'information reue par l'vnement loadend pour dterminer la condition de l'arrt. Toutefois, cet vnement permet de grer les tches ncessaires la fin des transferts.

Obtenir la date de dernire modification

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 rcuprer que les en-ttes
  "votrepage.html",
);
req.onload = getHeaderTime;
req.send();

Raliser une action lorsque la date de dernire modification change

Crons 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 rcuprer que les en-ttes */,
    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 modifie le ${new Date(
      nModified,
    ).toLocaleString()}!`,
  );
});

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

Utiliser XMLHttpRequest entre diffrentes origines

Les navigateurs prennent en charge les requtes entre diffrents sites/origines en implmentant le standard CORS (Cross-Origin Resource Sharing (pour  partage des ressources entre diffrentes origines ). Tant que le serveur est configur afin d'autoriser les requtes depuis l'origine de votre application web, XMLHttpRequest fonctionnera correctement. Dans le cas contraire, une exception INVALID_ACCESS_ERR sera dclenche.

Outrepasser le cache

Pour outrepasser le cache avec une mthode qui fonctionne dans les diffrents navigateurs, on pourra ajouter un horodatage l'URL en s'assurant d'encoder correctement la valeur (avec ? ou & o c'est ncessaire). 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 requte 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);

Securit

La mthode recommande pour autoriser les requtes scriptes entre diffrentes origines est d'inclure l'en-tte HTTP Access-Control-Allow-Origin dans la rponse la requte XHR.

Interruptions des requtes XHR

Si votre requte XHR se termine avec status=0 et statusText=null, cela signifie que son excution n'a pas t autorise. Elle n'a pas t envoye (UNSENT). Cela se produit gnralement lorsque l'origine de la requte a chang entre la cration et l'ouverture qui suit avec open(). Cela peut par exemple se produire lorsqu'une requte XHR est dclenche pour un vnement onunload d'une fentre. La requte est cre lorsque la fentre fermer existe encore, mais l'envoi qui suit (avec open()) se produit lorsque la fentre a perdu le focus et l'a pass une autre fentre. Pour viter ce problme, le mieux consistera placer un gestionnaire d'vnements DOMActivate sur la nouvelle fentre lorsque la fentre fermer reoit l'vnement unload.

Spcifications

Compatibilit des navigateurs

Voir aussi

• Utiliser l'API Fetch
• Prise en charge de HTML dans XMLHttpRequest
• Contrle d'accs HTTP (CORS)
• Spcification WHATWG pour l'objet XMLHttpRequest