L'objet JavaScript XMLHttpRequest

L'objet XMLHttpRequest permet aux scripts d'exécuter des fonctions client HTTP, telles que l'envoi de données de formulaire ou le chargement de données de manière asynchrone à partir d'un serveur.

L'API XMLHttpRequest est une implémentation partielle de la norme XHR de niveau 1 du W3C, à l'exception de ce qui suit :

• Elle n'applique pas la politique de la même origine.

Envoi de requêtes

Procédez comme suit pour envoyer une requête à l'aide de l'API XMLHttpRequest:

1. Créez un objet XMLHttpRequest.
2. Attribuez une fonction de rappel au gestionnaire de signal onreadystatechange.
3. Appelez open() avec la méthode HTTP appropriée et l'URL à demander.
4. Appelez send()

La fonction de rappel gère la réponse HTTP à une demande. Il est conseillé de vérifier si l'état prêt est DONE dans le gestionnaire, avant d'utiliser l'une des méthodes suivantes pour lire la réponse :

• response
• responseText
• responseXML

L'exemple suivant montre comment envoyer une requête et lire la réponse :

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls
import "request.js" as XHR

ApplicationWindow {
      width: 640
      height: 640
      visible: true

      ColumnLayout {
           anchors.fill: parent

           RowLayout {
               Layout.fillWidth: true

               TextField {
                   id: urlTextField
                   text: "https://www.example.com/index.html"
                   Layout.fillWidth: true
               }
               Button {
                   text: qsTr("Send!")
                   onClicked: XHR.sendRequest(urlTextField.text, function(response) {
                       statusTextField.text = response.status;
                       let isPlainText = response.contentType.length === 0

                       contentTypeTextField.text = isPlainText ? "text" : response.contentType;

                       if (isPlainText)
                           contentTextArea.text = response.content;
                   });
               }
           }

           GridLayout {
               columns: 2

               Layout.fillWidth: true

               Label {
                   text: qsTr("Status code")

                   Layout.fillWidth: true
               }
               Label {
                   text: qsTr("Response type")

                   Layout.fillWidth: true
               }
               TextField {
                    id: statusTextField

                    Layout.fillWidth: true
               }
               TextField {
                    id: contentTypeTextField

                    Layout.fillWidth: true
               }
           }
           Flickable {
               clip: true
               contentWidth: contentTextArea.width
               contentHeight: contentTextArea.height
               Text {
                    id: contentTextArea
               }

               Layout.fillWidth: true
               Layout.fillHeight: true
               ScrollBar.vertical: ScrollBar {}
               ScrollBar.horizontal: ScrollBar {}
           }
      }
}

L'extrait précédent connecte le signal du bouton cliqué à une fonction externe sendRequest. L'URL d'une ressource est transmise comme premier argument, et une fonction de rappel pour gérer les mises à jour de l'interface utilisateur est transmise comme second argument. La fonction sendRequest, qui existe dans un fichier externe request.js, peut être mise en œuvre de la manière suivante :

function sendRequest(url, callback)
{
    let request = new XMLHttpRequest();

    request.onreadystatechange = function() {
        if (request.readyState === XMLHttpRequest.DONE) {
            let response = {
                status : request.status,
                headers : request.getAllResponseHeaders(),
                contentType : request.responseType,
                content : request.response
            };

            callback(response);
        }
    }

    request.open("GET", url);
    request.send();
}

L'extrait précédent suit les quatre étapes simples mentionnées au début. Il instancie d'abord l'objet XMLHttpRequest et affecte une fonction de rappel pour gérer la réponse. Il appelle également open() avec une méthode HTTP et une URL, avant d'envoyer la requête au serveur. Notez que le deuxième argument de sendRequest est appelé à la fin de onreadystatechange, afin de gérer les mises à jour de l'interface utilisateur en fonction de la réponse HTTP.

Définissez la variable d'environnement QML_XHR_DUMP à 1 si vous souhaitez déboguer une requête. Cela permettra d'enregistrer les informations suivantes :

• Type de méthode (GET ou POST), URL et corps des requêtes envoyées.
• URL et corps des réponses reçues.
• Erreur de réseau, le cas échéant.

Accès aux fichiers locaux

Par défaut, vous ne pouvez pas utiliser l'objet XMLHttpRequest pour lire des fichiers à partir de votre système de fichiers local. Si vous souhaitez utiliser cette fonctionnalité pour accéder à des fichiers locaux, vous pouvez définir les variables d'environnement suivantes sur 1.

• QML_XHR_ALLOW_FILE_READ
• QML_XHR_ALLOW_FILE_WRITE

document responseXML

L'arbre DOM responseXML XML actuellement pris en charge par QML est un sous-ensemble réduit de l'API DOM Level 3 Core prise en charge dans un navigateur Web. Les objets et propriétés suivants sont pris en charge par l'implémentation QML :

void XMLHttpRequest::abort()

Annule la requête en cours.

La propriété readyState est remplacée par XMLHttpRequest.UNSENT et le signal readystatechange est émis.

string XMLHttpRequest::getAllResponseHeaders()

Renvoie un String des en-têtes reçus de la dernière réponse.

Voici un exemple d'en-tête de réponse :

content-encoding: gzip
content-type: text/html; charset=UTF-8
date: Mon, 06 Feb 2023 09:00:08 GMT
expires: Mon, 13 Feb 2023 09:00:08 GMT
last-modified: Thu, 17 Oct 2019 07:18:26 GMT

string XMLHttpRequest::getResponseHeader(headerName)

Renvoie soit la valeur headerName de la dernière réponse, soit un String vide, si le headerName est manquant.

void XMLHttpRequest::open(method, url, async)

Spécifiez le HTTP method que vous voulez que la requête utilise, ainsi que le url que vous souhaitez demander. Veillez à toujours appeler cette fonction avant send(). Un troisième paramètre facultatif async peut être utilisé pour décider si la requête doit être asynchrone ou non. La valeur par défaut est true.

Emet le signal readystatechange, qui appelle le gestionnaire onreadystatechange avec la propriété readyState fixée à XMLHttpRequest.OPENED.

void XMLHttpRequest::send(data)

Envoie la requête au serveur. Vous pouvez utiliser l'argument facultatif data pour ajouter des données supplémentaires au corps de la requête. Cela peut être utile pour les requêtes POST, où vous souhaitez généralement que la requête contienne des données supplémentaires.

La propriété readyState est mise à jour une fois qu'une réponse a été reçue du serveur et pendant que la réponse est en cours de traitement. Elle prend d'abord la valeur HEADERS_RECEIVED, puis LOADING, et enfin DONE, une fois que la réponse a été entièrement traitée. Le signal readystatechange est émis chaque fois que readyState est mis à jour.

void XMLHttpRequest::setRequestHeader(header, value)

Ajoute un nouvel en-tête à la prochaine requête que vous souhaitez envoyer. Il s'agit d'une paire clé-valeur, qui a le nom header et la valeur correspondante value.

void XMLHttpRequest::overrideMimeType(mime)

Force XMLHttpRequest à interpréter les données reçues dans la prochaine réponse HTTP comme si elles avaient le type MIME mime, plutôt que celui fourni par le serveur.

function XMLHttpRequest::onreadystatechange

Choisissez une fonction de rappel à invoquer lorsque l'état de préparation de l'objet XMLHttpRequest change.

enumeration XMLHttpRequest::readyState

Indique l'état actuel de l'objet XMLHttpRequest.

La valeur peut être l'une des suivantes

string XMLHttpRequest::responseURL

Renvoie l'url qui a été utilisée pour récupérer les données de la réponse, après les redirections éventuelles.

string XMLHttpRequest::responseText

Renvoie une adresse String contenant les données reçues de la dernière réponse.

var XMLHttpRequest::responseXML

Renvoie soit un Document, soit un null, si le contenu de la réponse ne peut pas être analysé en tant que XML ou HTML. Voir la section sur le document responseXML pour plus d'informations.

var XMLHttpRequest::response

Retourne soit un String, un ArrayBuffer, ou un Document, en fonction du type de réponse de la dernière requête.

string XMLHttpRequest::responseType

Renvoie une adresse String décrivant le type de contenu de la dernière réponse reçue.

• Si le type de réponse est "text" ou un String vide, le contenu de la réponse est un String encodé en UTF-16.
• Si le type de réponse est "arraybuffer", cela signifie que le contenu de la réponse est un ArrayBuffer contenant des données binaires.
• Si le type de réponse est "json", le contenu de la réponse doit être un JSON Document.
• Si le type de réponse est "document", cela signifie que le contenu de la réponse est un XML Document, qui peut être lu en toute sécurité avec la propriété responseXML.

int XMLHttpRequest::status

Renvoie le code d'état de la dernière réponse reçue.

string XMLHttpRequest::statusText

Renvoie une adresse String contenant le message d'état associé au code d'état de la dernière réponse reçue.