XML DOM - Objet XMLHttpRequest

Objet XMLHttpRequest

L'objet XMLHttpRequest offre un accès complet au protocole HTTP, y compris la capacité à effectuer des requêtes POST et HEAD ainsi que des requêtes GET classiques. XMLHttpRequest peut renvoyer la réponse du serveur Web de manière synchrone ou asynchrone et peut renvoyer le contenu sous forme de texte ou de document DOM.

Bien que nommé XMLHttpRequest, il n'est pas limité à l'utilisation avec des documents XML : il peut recevoir n'importe quel type de document texte.

l'objet XMLHttpRequest est nommé AJAX une fonctionnalité clé de l'architecture des applications Web.

le support du navigateur

XMLHttpRequest bénéficie d'une bonne prise en charge par tous les navigateurs modernes. La seule dépendance du navigateur concerne la création de l'objet XMLHttpRequest. Dans IE 5 et IE 6, il est nécessaire d'utiliser le constructeur spécifique à IE ActiveXObject(). Comme dans Objet XMLHttpRequest Ce qui est présenté dans cette section.

Standardisation W3C

L'objet XMLHttpRequest n'est pas encore standardisé, mais le W3C a commencé à travailler sur la standardisation. Le contenu de ce manuel est basé sur les projets de draft de standardisation.

L'implémentation actuelle de XMLHttpRequest est assez cohérente. Mais il y a des différences mineures avec la norme. Par exemple, une implémentation peut renvoyer null, tandis que la norme nécessite une chaîne vide, ou l'implémentation peut définir readyState sur 3 sans garantir que tous les en-têtes de réponse sont disponibles.

Propriété

readyState

L'état de la demande HTTP. Lorsque XMLHttpRequest est créé pour la première fois, la valeur de cette propriété commence à 0 et augmente jusqu'à ce que la réponse HTTP complète soit reçue.

Chaque l'un des 5 états a un nom informel associé. Le tableau suivant liste les états, les noms et les significations :

Statut Nom Description
0 Uninitialized État initialisé. L'objet XMLHttpRequest a été créé ou réinitialisé par la méthode abort().
1 Open La méthode open() a été appelée, mais la méthode send() n'a pas été appelée. La demande n'a pas été envoyée.
2 Sent La méthode Send() a été appelée, la demande HTTP a été envoyée au serveur Web. Pas de réponse reçue.
3 Receiving Tous les en-têtes de réponse ont été reçus. Le corps de la réponse commence à être reçu mais n'est pas terminé.
4 Loaded L'ensemble de la réponse HTTP a été reçu.

La valeur de readyState ne décrémente pas, sauf si abort() ou open() est appelé pendant le traitement d'une demande. Chaque fois que la valeur de cette propriété augmente, l'handlede l'événement onreadystatechange est déclenché.

responseText

Jusqu'à présent, le corps de la réponse reçue par le serveur (sans inclure les en-têtes), ou une chaîne vide si les données n'ont pas encore été reçues.

Si le readyState est inférieur à 3, cette propriété est une chaîne vide. Lorsque le readyState est 3, cette propriété renvoie la partie de la réponse reçue jusqu'à présent. Si le readyState est 4, cette propriété contient le corps complet de la réponse.

Si la réponse contient un en-tête spécifiant le codage de caractères pour le corps de réponse, utilisez ce codage. Sinon, on suppose qu'il utilise Unicode UTF-8.

responseXML

La réponse à la demande, analysée en XML et utilisée comme Objet Documentretourner.

status

retourné par le serveur Code d'état HTTP，comme 200 pour indiquer une réussite, et 404 pour indiquer une erreur "Not Found".. L'accès à cette propriété lorsque le readyState est inférieur à 3 provoque une exception.

statusText

Cette propriété spécifie le code d'état HTTP de la requête en utilisant un nom plutôt qu'un numéro. Par exemple, lorsque l'état est 200, il est "OK", et lorsque l'état est 404, il est "Not Found". Comme pour la propriété status, l'accès à cette propriété lorsque le readyState est inférieur à 3 provoque une exception.

Gestionnaire d'événement

onreadystatechange

Fonction de gestion des événements appelée à chaque fois que la propriété readyState change. Elle peut également être appelée plusieurs fois lorsque le readyState est 3.

Méthode

abort()

Annuler la réponse actuelle, fermer la connexion et terminer toute activité réseau en cours.

Cette méthode réinitialise l'objet XMLHttpRequest à un état readyState de 0 et annule toutes les activités réseau en cours. Par exemple, si la requête prend trop de temps et que la réponse n'est plus nécessaire, vous pouvez appeler cette méthode.

getAllResponseHeaders()

Retourner les en-têtes de réponse HTTP sous forme de chaînes non analysées.

Si le readyState est inférieur à 3, cette méthode retourne null. Sinon, elle retourne tous les en-têtes de réponse HTTP envoyés par le serveur. Les en-têtes sont retournés en tant que chaînes individuelles, une par ligne. Chaque ligne est séparée par un retour chariot et un saut de ligne "\r\n".

getResponseHeader()

Retourner la valeur de l'en-tête HTTP HTTP spécifié. Le paramètre est le nom de l'en-tête HTTP HTTP à retourner. Vous pouvez utiliser n'importe quelle casse pour définir ce nom d'en-tête, et la comparaison avec l'en-tête de réponse n'est pas sensible à la casse.

La valeur de retour de cette méthode est la valeur de l'en-tête HTTP HTTP spécifié, qui est une chaîne vide si cette en-tête n'a pas été reçue ou si le readyState est inférieur à 3. Si plusieurs en-têtes de ce nom sont reçus, les valeurs des en-têtes sont concaténées et retournées, séparées par des virgules et des espaces.

open()

Initialiser les paramètres de requête HTTP, tels que l'URL et la méthode HTTP, mais ne pas envoyer la requête.

send()

Envoyer une requête HTTP en utilisant les paramètres passés à la méthode open() et le corps de requête optionnel passé à cette méthode.

setRequestHeader()

Définir ou ajouter une requête HTTP à une requête ouverte mais non envoyée.

XMLHttpRequest.open()

Initialiser les paramètres de requête HTTP

Syntaxe

open(method, url, async, username, password)

Le paramètre method est la méthode HTTP utilisée pour la requête. Les valeurs incluent GET, POST et HEAD.

Le paramètre url est le corps de la requête. La plupart des navigateurs appliquent une stratégie de sécurité de même origine et exigent que cet URL ait le même nom d'hôte et le même port que le texte contenant le script.

Le paramètre async indique que la requête doit être exécutée de manière asynchrone. Si ce paramètre vaut false, la requête est synchronisée, et l'appel à send() bloquera jusqu'à ce que la réponse soit complètement reçue. Si ce paramètre vaut true ou est omis, la requête est asynchrone et nécessite généralement un gestionnaire d'événement onreadystatechange.

Les paramètres username et password sont optionnels et fournissent des qualifications d'authentification nécessaires pour l'url. Si spécifiés, ils couvrent toute qualification spécifiée dans l'url elle-même.

Explication

Cette méthode initialise les paramètres de la requête pour leur utilisation future par la méthode send(). Elle met le readyState à 1, supprime toutes les en-têtes de requête spécifiées précédemment, ainsi que toutes les en-têtes de réponse reçues précédemment, et met les paramètres responseText, responseXML, status et statusText à leurs valeurs par défaut. Lorsque le readyState est 0 (quand l'objet XMLHttpRequest est créé ou après l'appel à la méthode abort()), ainsi que lorsque le readyState est 4 (après avoir reçu la réponse), l'appel à cette méthode est sûr. Lorsque cette méthode est appelée pour tout autre état, le comportement de la méthode open() est déterminé.

En plus de sauvegarder les paramètres de requête pour l'utilisation de la méthode send(), et de réinitialiser l'objet XMLHttpRequest pour une réutilisation, la méthode open() n'a pas d'autres comportements. Il faut noter en particulier que lorsque cette méthode est appelée, l'implémentation ne ouvre généralement pas une connexion réseau vers le serveur Web.

XMLHttpRequest.send()

Envoyer une requête HTTP

Syntaxe

send(body)

Si la méthode HTTP spécifiée par l'appel à open() est POST ou PUT, le paramètre body spécifie le corps de la requête, sous forme de chaîne ou Objet DocumentSi le corps de la requête n'est pas nécessaire, ce paramètre vaut null. Pour toute autre méthode, ce paramètre n'est pas disponible et doit être null (certains implémentations ne permettent pas de ne pas spécifier ce paramètre).

Explication

Cette méthode entraîne l'envoi d'une requête HTTP. Si open() n'a pas été appelé précédemment, ou plus précisément, si l'état de readyState n'est pas 1, send() lève une exception. Sinon, il envoie une requête HTTP composée des éléments suivants :

  • Les méthodes HTTP, l'URL et les qualifications d'authentification spécifiées lors de l'appel précédent open() (s'il y en a).
  • Les en-têtes de requête spécifiés lors de l'appel précédent setRequestHeader() (s'il y en a).
  • Passé à cette méthode body Paramètres.

Une fois la requête publiée, send() met l'état de readyState à 2 et déclenche l'handled onreadystatechange.

Si le paramètre async de la méthode précédemment appelée open() est faux, cette méthode bloquera et ne retournera pas jusqu'à ce que l'état de readyState soit 4 et que la réponse du serveur soit complètement reçue. Sinon, si le paramètre async est vrai ou que ce paramètre est omis, send() retourne immédiatement et, comme il sera expliqué plus tard, la réponse du serveur sera traitée dans un fil d'arrière-plan.

Si la réponse du serveur contient une redirection HTTP, la méthode send() ou le fil d'arrière-plan suivent automatiquement la redirection. Une fois que tous les en-têtes de réponse HTTP ont été reçus, send() ou le fil d'arrière-plan mettent l'état de readyState à 3 et déclenchent l'handled onreadystatechange. Si la réponse est longue, send() ou le fil d'arrière-plan peuvent déclencher l'handled onreadystatechange à l'état 3 : cela peut servir d'indicateur de progression de téléchargement. Enfin, lorsque la réponse est complète, send() ou le fil d'arrière-plan mettent l'état de readyState à 4 et déclenchent l'handled onreadystatechange pour la dernière fois.

XMLHttpRequest.setRequestHeader()

Syntaxe

setRequestHeader(name, value)

Le paramètre name est le nom de l'en-tête à définir. Ce paramètre ne doit pas inclure d'espaces, de deux-points ou de sauts de ligne.

Le paramètre value est la valeur de l'en-tête. Ce paramètre ne doit pas inclure de sauts de ligne.

Explication

La méthode setRequestHeader() spécifie un en-tête de requête HTTP, qui doit être inclus dans la requête publiée par l'appel suivant send(). Cette méthode ne peut être appelée que lorsque l'état de readyState est 1, par exemple, après avoir appelé open(), mais avant d'appeler send().

Si l'en-tête spécifié avec le nom désigné a déjà été défini, la nouvelle valeur de cet en-tête est : la valeur précédemment définie, ajoutée d'une virgule, d'un espace et de la valeur spécifiée par cette appelle.

Si l'appel open() spécifie des qualifications d'authentification, XMLHttpRequest envoie automatiquement une en-tête de requête d'authentification appropriée. Cependant, vous pouvez utiliser setRequestHeader() pour ajouter cette en-tête. De même, si le serveur Web a déjà enregistré et transmis un cookie associé à l'URL passée à open(), les en-têtes Cookie ou Cookie2 appropriés sont automatiquement inclus dans la requête. Vous pouvez ajouter ces cookies à l'en-tête en appelant setRequestHeader(). XMLHttpRequest peut également fournir une valeur par défaut pour l'en-tête User-Agent. Si cela se produit, toute valeur que vous spécifiez pour cet en-tête sera ajoutée à cette valeur par défaut.

Certaines en-têtes de requête sont automatiquement définies par XMLHttpRequest au lieu de cette méthode, conformément aux protocoles HTTP. Cela inclut les en-têtes liées à l'agent, telles que :

  • Host
  • Connection
  • Keep-Alive
  • Accept-charset
  • Accept-Encoding
  • If-Modified-Since
  • If-None-Match
  • If-Range
  • Range