Comment télécharger un fichier avec WinJS.xhr (HTML)

Article
12/11/2015

[ Cet article est destiné aux développeurs de Windows 8.x et Windows Phone 8.x qui créent des applications Windows Runtime. Si vous développez une application pour Windows 10, voir la Documentation ]

WinJS.xhr facilite le téléchargement de contenu web dans votre application. Cette rubrique explique comment télécharger un fichier à l’aide de WinJS.xhr, gérer les erreurs et signaler la progression du téléchargement. Elle explique aussi comment télécharger différents types de contenu.

La fonction WinJS.xhr renvoie un WinJS.Promise. Pour plus d’informations sur les méthodes asynchrones en général et sur les promesses JavaScript en particulier, voir Programmation asynchrone en JavaScript.

Avertissement Il est maintenant possible d’utiliser XMLHttpRequest pour transférer des objets extrêmement volumineux, comme les objets Blob et les objets FormData, dont le téléchargement peut prendre beaucoup de temps. Les applications pouvant être arrêtées à tout moment, il vaut mieux utiliser les API de chargement de fichier dans l’API Windows Runtime pour ces opérations. Pour plus d’informations sur le chargement de contenu, voir Comment charger un fichier.

Prérequis

Pour effectuer cette procédure, vous devez savoir créer une application de base qui utilise le modèle Bibliothèque Windows pour JavaScript. Pour obtenir de l’aide sur la création de votre première application, voir Créer votre première application Windows Runtime en JavaScript.

Configurer l’application pour accéder au Web

Les applications doivent ajouter certaines fonctionnalités de manière explicite, comme l’accès au réseau. Pour plus d’informations sur ces fonctionnalités, voir Déclarations des fonctionnalités d’application et Comment configurer les fonctionnalités réseau.

Dans Visual Studio, créez une application JavaScript vide.
Ouvrez le fichier package.appxmanifest, puis accédez à l’onglet Capacités.
Pour la version Windows de cet exemple, si la fonctionnalité Internet (Client) n’a pas encore été sélectionnée, faites-le maintenant. Si l’application doit pouvoir se connecter en qualité de client à des services Web sur un réseau domestique privé ou un réseau professionnel, la fonctionnalité Réseaux privés (client et serveur) est également nécessaire.

Pour la version Windows Phone de cet exemple, sélectionnez la fonctionnalité Internet (client et serveur).

Remarque Sur Windows Phone, il existe une seule fonctionnalité réseau (Internet (client et serveur), qui active tout l’accès réseau pour l’application.

Téléchargement de base

Au cours de cette étape, vous allez télécharger une page Web et signaler la fin du téléchargement.

Créez une application vide et nommez-la XhrExample.
Dans le corps du code HTML du fichier default.html, ajoutez un élément DIV destiné à contenir les rapports d’erreur, de progression et d’achèvement.
```
<div id="xhrReport"></div>
```
Dans le corps du code HTML du fichier default.html, ajoutez également un élément SCRIPT qui contient le code WinJS.xhr.
```
var xhrDiv = document.getElementById("xhrReport");
xhrDiv.style.color = "#000000";

WinJS.xhr({ url: "https://www.microsoft.com" })
    .done(function complete(result) {
        // Report download.
        xhrDiv.innerText = "Downloaded the page";
        xhrDiv.style.backgroundColor = "#00FF00";
});
```
Dans le code précédent, la fonction complete écrit dans l’élément DIV que le téléchargement est terminé.

Notez la syntaxe de WinJS.xhr. Cette fonction prend un seul paramètre dans lequel vous spécifiez les options. La seule option requise est url. La documentation de référence contient des informations sur les autres options.

Chaque promesse possède deux fonctions qui vous permettent de gérer les résultats d’une opération asynchrone : then et done. Les deux fonctions acceptent trois paramètres : une fonction qui est appelée lorsque le téléchargement est terminé (à savoir lorsque readyState a la valeur 4), une fonction qui est appelée lorsqu’une erreur se produit et une fonction appelée lorsque le téléchargement est en cours d’exécution (quand readyState a la valeur 2 ou 3). Seule la fonction done lève une exception si une erreur n’est pas gérée. Utilisez la fonction done si vous ne souhaitez pas fournir de fonction d’erreur.
Générez et exécutez l’application en mode débogage. Une zone verte contenant l’expression « Downloaded the page » doit apparaître.
À présent, essayez de provoquer une erreur afin de voir ce qui se passe. Pour ce faire, remplacez l’URL https://www.microsoft.com dans le code par http://www.nosuchsite.example. Lorsque vous exécutez l’application en mode débogage, vous devez être conduit à l’instruction debugger dans la fonction terminateAppHandler, dans le fichier WinJS base.js.

Traitement des erreurs

Au cours de cette étape, vous ajoutez un gestionnaire d’erreurs qui écrit dans l’élément DIV lorsqu’une erreur se produit.

Ajoutez un gestionnaire d’erreurs au code que vous avez ajouté à l’étape 3 ci-dessus. Avec WinJS.xhr, la fonction error possède un paramètre qui représente la requête.

var xhrDiv = document.getElementById("xhrReport");

WinJS.xhr({ url: "http://www.nosuchsite.example" })
    .done(function complete(result) {
        // Report download.
        xhrDiv.innerText = "Downloaded the page";
        xhrDiv.style.backgroundColor = "#00FF00"; 
        },
        function error(result){
            xhrDiv.innerHTML = "Got error: " + result.statusText;
            xhrDiv.style.backgroundColor = "#FF0000";
     });

Lorsque vous exécutez l’application, une zone rouge signalant l’erreur doit apparaître.

Indication de la progression

Au cours de cette étape, vous indiquez la progression du téléchargement en fournissant une fonction progress à la fonction done.

Ajoutez un gestionnaire d’erreurs au code que vous avez ajouté à l’étape précédente. Avec WinJS.xhr, la fonction progress possède un paramètre qui représente la requête.

var xhrDiv = document.getElementById("xhrReport");

WinJS.xhr({ url: "https://www.microsoft.com" })
    .done(function complete(result) {
        // Report download.
            xhrDiv.innerText = "Downloaded the page";
            xhrDiv.style.backgroundColor = "#00FF00"; 
        },
        function error(error){
            xhrDiv.innerHTML = "Got error: " + error.statusText;
            xhrDiv.style.backgroundColor = "#FF0000";
        }, 
        function progress(result) {
            xhrDiv.innerText = "Ready state is " + result.readyState;
            xhrDiv.style.backgroundColor = "#0000FF";
    });

Lorsque vous exécutez le code, une zone bleue contenant les mots « Ready state is 2 » ou « Ready state is 3 » doit s’afficher avant une zone verte contenant les mots « Downloaded the page ». (Pour voir la zone bleue, vous devrez peut-être ralentir l’exécution du code en définissant un point d’arrêt dans la fonction progress.)

Téléchargement de différents types de contenu

Vous pouvez télécharger différents types de contenu en utilisant WinJS.xhr. Vous indiquez le type de contenu dans l’option responseType de WinJS.xhr.

Les types pris en charge sont les suivants :

arraybuffer : le type de response est ArrayBuffer. Ce type est utilisé pour représenter le contenu binaire sous forme de tableau de type Int8, Int64 ou tout autre type entier ou flottant. (Pour plus d’informations sur les différents tableaux typés actuellement pris en charge en JavaScript, voir Tableaux typés.) Les propriétés responseText et responseXML sont undefined.

Ce code montre comment gérer une réponse arraybuffer :


<div id="xhrDiv"></div>
<script type="text/javascript">
    WinJS.xhr({ url: "https://www.microsoft.com", responseType: "arraybuffer" })
        .done(function complete(result) {
            var arrayResponse = result.response;
            var ints = new Uint32Array(arrayResponse.byteLength / 4);

            xhrDiv.style.backgroundColor = "#00FF00";
            xhrDiv.innerText = "Array is " + ints.length + "uints long";
        });
</script>

blob : le type de response est Blob. Il est utilisé pour représenter le contenu binaire sous forme d’entité binaire unique. Les propriétés responseText et responseXML sont undefined.

Ce code montre comment gérer un blob :

WinJS.xhr({ url: "https://www.microsoft.com/windows/Framework/images/win_logo.png", responseType: "blob" })
    .done(
        function (request) {
            var imageBlob = URL.createObjectURL(request.response);
            var imageTag = xhrDiv.appendChild(document.createElement("image"));
            imageTag.src = imageBlob;
        });

document : le type de responseest un objet DOM (Document Object Model) XML. Il est utilisé pour représenter du contenu XML, c’est-à-dire, du contenu du type MIME « text/xml ». Si le type MIME est différent de « text/xml », responseXML est du même type et responseText est undefined.
json : le type de response est String. Ce type est utilisé pour représenter les chaînes JSON. responseText est également de type String, tandis que responseXML est undefined.
ms-stream : le type de response est msStream, tandis que responseText et responseXML sont undefined. Ce type de réponse n’est pas défini dans la spécification W3C, mais il est pris en charge pour gérer les données diffusées en continu. Pour plus d’informations, voir Améliorations de XMLHttpRequest.

text (par défaut) : le type de response et responseText est String.

Cet exemple montre comment gérer une réponse text :

WinJS.xhr({ url: "http://www.msdn.microsoft.com/library", responseType: "text" 
    .done(
        function (request) {
            var text = request.responseText;
            var subText = text.substring(text.indexOf("Welcome"), text.indexOf("services.") + 9);
            xhrDiv.innerHTML = subText;
    });