L'objet JavaScript XMLHttpRequest

L'objet XMLHttpRequest permet aux scripts d'exécuter des fonctionnalités client HTTP, telles que l'envoi de données de formulaire ou le chargement asynchrone de données depuis un serveur.

L'API XMLHttpRequest est une implémentation partielle de la norme W3C XHR Level 1, à l'exception suivante :

• elle n'applique pas la politique de 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 la méthode open() en indiquant la méthode HTTP et l'URL appropriées pour la requête.
4. Appelez la méthode send()

La fonction de rappel gère la réponse HTTP d'une requête. Il est recommandé de vérifier si la propriété ` readyState` est à la valeur ` 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 de code précédent relie le signal « clicked » du bouton à une fonction « sendRequest » externe. Une URL de ressource est transmise en tant que premier argument, et une fonction de rappel chargée de gérer les mises à jour de l'interface utilisateur est transmise en tant que deuxième argument. La fonction « sendRequest », qui se trouve dans un fichier externe « request.js », peut être implémentée comme suit :

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 de code ci-dessus suit les quatre étapes simples mentionnées au début. Il instancie d'abord l'objet XMLHttpRequest, puis lui attribue une fonction de rappel pour gérer la réponse. Il appelle également la méthode open() en lui transmettant 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 ` sur ` 1 ` si vous souhaitez déboguer une requête. Cela permettra de consigner 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 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'arborescence DOM XML « responseXML » actuellement prise en charge par QML est un sous-ensemble réduit de l'API DOM Level 3 Core prise en charge par les navigateurs 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.

Elle définit la propriété `readyState ` sur ` XMLHttpRequest.UNSENT ` et émet le signal ` readystatechange `.

chaîne XMLHttpRequest::getAllResponseHeaders()

Renvoie un String des en-têtes reçus lors 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 de l'headerName de la dernière réponse, soit un String vide si l'headerName est absent.

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

Spécifie l’ method HTTP que vous souhaitez utiliser pour la requête, ainsi que l’ url que vous souhaitez demander. Veillez à toujours appeler cette fonction avant send(). Un troisième paramètre facultatif, async, permet de déterminer si la requête doit être asynchrone ou non. La valeur par défaut est true.

Émet le signal « readystatechange », qui appelle le gestionnaire « onreadystatechange » avec la propriété « readyState » définie sur « 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 s’avérer utile pour les requêtes POST, où l’on souhaite généralement que la requête contienne des données supplémentaires.

La propriété `readyState` est mise à jour dès qu’une réponse a été reçue du serveur, et pendant le traitement de la réponse. Elle est d’abord définie sur ` HEADERS_RECEIVED`, puis sur ` LOADING`, et enfin sur ` DONE` une fois la réponse entièrement traitée. Le signal ` readystatechange ` est émis à chaque mise à jour de `readyState`.

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, dont le nom est header et la valeur correspondante value.

void XMLHttpRequest::overrideMimeType(mime)

Force l’ 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 que vous souhaitez voir invoquée chaque fois que l’état readyState de l’objet XMLHttpRequest change.

énumération XMLHttpRequest::readyState

Indique l’état actuel de l’objet ` XMLHttpRequest `.

La valeur peut être l'une des suivantes :

chaîne XMLHttpRequest::responseURL

Renvoie l'URL qui a été utilisée pour récupérer les données de réponse, une fois toutes les redirections effectuées.

chaîne XMLHttpRequest::responseText

Renvoie un objet ` String ` contenant les données reçues lors de la dernière réponse.

var XMLHttpRequest::responseXML

Renvoie soit un objet ` Document`, soit un objet ` null`, si le contenu de la réponse ne peut pas être analysé en XML ou en HTML. Reportez-vous à la section « responseXML » de la documentation pour plus d'informations.

var XMLHttpRequest::response

Renvoie soit un ` String`, soit un ` ArrayBuffer`, soit un ` Document`, en fonction du ` responseType ` de la dernière requête.

chaîne XMLHttpRequest::responseType

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

• Si le type de réponse est « text » ou une chaîne vide String, le contenu de la réponse est une chaîne encodée en UTF-16 String.
• Si le type de réponse est « arraybuffer », cela signifie que le contenu de la réponse est un objet ` ArrayBuffer ` contenant des données binaires.
• Si le type de réponse est « json », le contenu de la réponse doit être un Document au format JSON.
• Si le type de réponse est « document », cela signifie que le contenu de la réponse est un Document XML, qui peut être lu en toute sécurité à l’aide de 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 String contenant le message d'état associé au code d'état de la dernière réponse reçue.