Come scaricare un file con WinJS.xhr (HTML)

Articolo
12/11/2015

[ Questo articolo è rivolto agli sviluppatori per Windows 8.x e Windows Phone 8.x che realizzano app di Windows Runtime. Gli sviluppatori che usano Windows 10 possono vedere Documentazione aggiornata ]

WinJS.xhr semplifica l'accesso ai contenuti Web nella tua app. Questo argomento illustra come scaricare un file mediante WinJS.xhr, gestire gli eventuali errori e segnalare lo stato del download. Spiega inoltre come scaricare tipi diversi di contenuto.

La funzione WinJS.xhr restituisce un oggetto WinJS.Promise. Per ulteriori informazioni sui metodi asincroni in generale e sulle promesse JavaScript in particolare, vedi Programmazione asincrona in JavaScript.

Avviso Ora è possibile usare XMLHttpRequest per trasferire oggetti di dimensioni molto grandi, ad esempio oggetti Blob e FormData, il cui completamento può richiedere molto tempo. Poiché le app possono essere terminate in qualsiasi momento, per eseguire queste operazioni ti consigliamo di usare le API di caricamento file nell'API Windows Runtime. Per altre info sul caricamento di contenuto, vedi Come caricare un file.

Prerequisiti

Per completare questa procedura, devi saper creare un'app di base che usa il modello della libreria Windows per JavaScript. Se hai bisogno di aiuto per creare la tua prima app, vedi Creare la prima app di Windows Runtime in JavaScript.

Configurare l'app per l'accesso al Web

Le app devono aggiungere alcune funzionalità in modo esplicito, ad esempio l'accesso alla rete. Per altre informazioni sulle funzionalità, vedi Dichiarazioni di funzionalità delle app e Come configurare le funzionalità di rete.

In Visual Studio crea un'app JavaScript vuota.
Apri il file package.appxmanifest e vai alla scheda Funzionalità.
Per la versione di Windows dell'esempio, la funzionalità Internet (client) dovrebbe essere già selezionata, se non lo è selezionala. Se l'app deve essere in grado di connettersi come client a servizi Web su una rete domestica o aziendale, è necessaria anche la funzionalità Reti private (client e server).

Per la versione di Windows Phone dell'esempio, seleziona la funzionalità Internet (client e server).

Nota In Windows Phone, c'è solo una funzionalità di rete (Internet (client e server)) che consente l'accesso a tutte le reti per l'app.

Download di base

In questo passaggio scaricherai una pagina Web e segnalerai il completamento del download.

Crea un'app vuota e assegnale il nome XhrExample.
Nel corpo del codice HTML nel file default.html aggiungi un elemento DIV per contenere le segnalazioni di completamento, in corso ed errore.
```
<div id="xhrReport"></div>
```
Sempre nello stesso punto aggiungi un elemento SCRIPT che contiene il codice 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";
});
```
Nel codice precedente la funzione complete scrive all'elemento DIV che il download è completato.

Nota la sintassi di WinJS.xhr. Questa funzione accetta un solo parametro in cui specifichi le opzioni. L'unica opzione obbligatoria è url. Nella documentazione di riferimento trovi informazioni sulle altre opzioni.

Ogni promessa ha due funzioni che puoi usare per gestire i risultati di un'operazione asincrona, then e done. Entrambe le funzioni accettano tre parametri: una funzione chiamata al completamento del download (ovvero quando readyState è 4), una funzione chiamata quando è presente un errore e una funzione chiamata mentre il download è in corso (ovvero quando readyState è 2 o 3). Solo la funzione done genera un'eccezione se un errore non è gestito. Usa la funzione done se non vuoi fornire una funzione di gestione degli errori.
Compila ed esegui l'app in modalità debug. Dovresti vedere una finestra verde che contiene le parole"Downloaded the pag".
Ora, prova a provocare un errore per vedere ciò che accade. Sostituisci l'URL https://www.microsoft.com nel codice con http://www.nosuchsite.example. Quando esegui l'app in modalità debug, deve essere visualizzata l'istruzione debugger nella funzione terminateAppHandler del file base.js WinJS.

Gestione degli errori

In questo passaggio aggiungerai un gestore dell'errore che scrive all'elemento DIV quando si verifica un errore.

Aggiungi un gestore dell'errore al codice che hai aggiunto nel passaggio 3 precedente. Con WinJS.xhr, la funzione di errore ha un parametro che rappresenta la richiesta.

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";
     });

Quando esegui l'app, dovrebbe essere presente una finestra rossa che segnala l'errore.

Segnalazione dell'avanzamento

In questo passaggio segnalerai l'avanzamento del download fornendo una funzione di avanzamento alla funzione done.

Aggiungi un gestore dell'avanzamento al codice che hai aggiunto nel passaggio precedente. Con WinJS.xhr, la funzione di avanzamento ha un parametro che rappresenta la richiesta.

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";
    });

Quando esegui il codice, dovresti vedere una finestra blu che contiene le parole "Ready state is 2" o "Ready state is 3" prima di vedere una finestra verde che contiene le parole "Downloaded the page". Per vedere la finestra blu può essere necessario rallentare le operazioni con un punto di interruzione.

Download di diversi tipi di contenuto

WinJS.xhr ti consente di scaricare diversi tipi di contenuto. Devi indicare il tipo di contenuto nell'opzione responseType di WinJS.xhr.

Sono supportati i tipi seguenti:

arraybuffer: il tipo di response è ArrayBuffer. Questo tipo viene usato per rappresentare contenuto binario come matrice di tipo Int8 o Int64 o un altro tipo integer o a virgola mobile. Vedi Matrici tipizzate per altre informazioni sulle matrici tipizzate attualmente supportate in JavaScript. Le proprietà responseText e responseXML sono undefined.

Il codice seguente mostra come gestire una risposta 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: il tipo di response è un Blob. Consente di rappresentare contenuti binari come un'entità binaria singola. Le proprietà responseText e responseXML sono undefined.

Il codice seguente mostra come gestire 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: il tipo di response è un oggetto XML Document Object Model (DOM). Consente di rappresentare contenuto XML, vale a dire il contenuto che dispone di un tipo MIME "text/xml". Se il tipo MIME è qualcosa di diverso da "text/xml", l'oggetto responseXML è dello stesso tipo e responseText è undefined.
json: il tipo di response è String. Consente di rappresentare stringhe JSON. Anche responseText è di tipo String, mentre responseXML è undefined.
ms-stream: il tipo di response è msStream, mentre responseText e responseXML sono undefined. Questo tipo di risposta non è definito nella specifica W3C, ma è supportato per semplificare la gestione dei dati di streaming. Per altre informazioni, vedi Miglioramenti di XMLHttpRequest.

text (predefinito): il tipo di response e responseText sono String.

L'esempio seguente mostra come gestire una risposta 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;
    });