Como baixar um arquivo com WinJS.xhr (HTML)

Artigo
12/12/2015

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

O WinJS.xhr fornece uma maneira fácil de baixar conteúdo da Web em seu aplicativo. Este tópico mostra como baixar um arquivo usando WinJS.xhr, tratar erros e relatar o progresso do download. Ele mostra também como baixar diferentes tipos de conteúdo.

A função WinJS.xhr retorna um WinJS.Promise. Para obter mais informações sobre métodos assíncronos em geral e promessas de JavaScript em particular, consulte Programação assíncrona em JavaScript.

Aviso Agora também é possível usar XMLHttpRequest para transferir objetos muito grandes, como objetos Blob e FormData, o que pode levar muito tempo para concluir. Como os aplicativos podem ser encerrados a qualquer momento, considere a possibilidade de usar as APIs de carregamento de arquivos da API do Tempo de Execução do Windows para essas operações. Para obter mais informações sobre o carregamento de conteúdo, consulte Como carregar um arquivo.

Pré-requisitos

Para concluir este procedimento, você precisa criar um aplicativo básico que use o modelo da Biblioteca do Windows para JavaScript. Para obter ajuda na criação de seu primeiro aplicativo, consulte Criar seu primeiro aplicativo do Tempo de Execução do Windows em JavaScript.

Configurar seu aplicativo para acessar a Web

Os aplicativos precisam adicionar determinados recursos explicitamente, como acesso à rede. Para obter mais informações sobre os recursos, consulte Declarações de recursos do aplicativo e Como configurar os recursos de rede.

No Visual Studio, crie um aplicativo em JavaScript em branco.
Abra o arquivo package.appxmanifest e vá para a guia Recursos.
Para a versão do Windows da amostra, a funcionalidade Internet (Cliente) já deverá estar selecionada, mas caso não esteja, selecione-a agora. O aplicativo talvez precise se conectar como um cliente a serviços Web em uma rede doméstica ou corporativa, então, a funcionalidade Redes Privadas (Cliente e Servidor) também é necessária.

Para a versão do Windows Phone da amostra, selecione a funcionalidade Internet (Cliente e Servidor).

Observação No Windows Phone, há apenas um recurso de rede, Internet (Cliente e Servidor), que permite o total acesso à rede do aplicativo.

Download básico

Nesta etapa, você baixará uma página da Web e informará quando o download terminou.

Crie um aplicativo em branco e o chame-o de XhrExample.
No corpo do HTML no arquivo default.html, adicione um elemento DIV para conter a notificação concluída, o progresso e os relatórios de erro.
```
<div id="xhrReport"></div>
```
Também no corpo do HTML do arquivo default.html, adicione um elemento SCRIPT que contenha o código 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";
});
```
No código acima, a função complete escreve no elemento DIV que o download foi concluído.

Note a sintaxe de WinJS.xhr. Esta função tem um parâmetro único no qual você especifica as opções. A única opção necessária é url. Você pode ler sobre as outras opções na documentação de referência.

Cada promessa tem duas funções que você pode usar para manipular os resultados de uma operação assíncrona: then e done. As duas funções usam três parâmetros: uma função que é chamada quando o download é concluído (isto é, quando readyState for 4), uma função que é chamada quando há um erro e uma função que é chamada enquanto o download está em andamento (quando readyState for 2 ou 3). Somente a função done gerará uma exceção, se um erro não for tratado. Você deverá usar a função done quando não quiser fornecer uma função de erro.
Ao fazer isso, execute o aplicativo no modo de depuração. Você deve ver uma caixa verde contendo as palavras "Downloaded the page".
Agora tente provocar um erro de forma que você possa ver o que acontece. Substitua a URL https://www.microsoft.com no código por http://www.nosuchsite.example. Ao executar o aplicativo no modo de depuração, você deverá ser conduzido à instrução debugger na função terminateAppHandler do arquivo base.js do WinJS.

Manipulando erros

Nesta etapa, você adicionará um manipulador de erro que escreve no DIV quando ocorre um erro.

Adicione um manipulador de erro ao código que você adicionou na etapa 3 acima. Com WinJS.xhr, a função error tem um parâmetro que representa a solicitação.

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

Ao executar o aplicativo, você deve ver uma caixa vermelha que informa o erro.

Informando o progresso

Nesta etapa, você informará sobre o progresso do download fornecendo uma função de progresso para a função done.

Adicione um manipulador de progresso ao código que você adicionou na etapa anterior. Com WinJS.xhr, a função de progresso tem um parâmetro que representa a solicitação

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 você executar o código, deverá ver uma caixa azul contendo as palavras "Ready state is 2" ou "Ready state is 3" antes de ver uma caixa verde contendo as palavras "Downloaded the page". (Para ver a caixa azul, talvez seja necessário usar um ponto de interrupção.)

Baixando tipos diferentes de conteúdo

Você pode baixar diferentes tipos de conteúdo usando WinJS.xhr. Você indica o tipo de conteúdo na opção responseType de WinJS.xhr.

Há suporte para estes tipos:

arraybuffer: o tipo de response é um ArrayBuffer. Esse tipo é usado para representar conteúdo binário como uma matriz do tipo Int8 ou Int64, ou de outro tipo de inteiro ou float. (Consulte Matrizes Digitadas para saber mais sobre as diferentes matrizes digitadas atualmente compatíveis com JavaScript.) As propriedades responseText e responseXML são undefined.

Este código mostra como tratar uma resposta 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: o tipo de response é um Blob. Ele é usado para representar conteúdo binário como uma única entidade binária. As propriedades responseText e responseXML são undefined.

Este código mostra como tratar um 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: o tipo de response é um objeto XML DOM (XML Document Object Model). Ele é usado para representar conteúdo XML, ou seja, conteúdo que tem um tipo MIME "texto/xml". Se o tipo MIME não for "texto/xml", a responseXML será do mesmo tipo e o responseText será undefined.
json: o tipo de response é String. Ele é usado para representar cadeias de caracteres JSON. responseText também é do tipo String e responseXML é undefined.
ms-stream: o tipo de response é msStream, e responseText e responseXML são undefined. Esse tipo de resposta não é definido na especificação W3C, mas é compatível para facilitar a manipulação de dados de streaming. Para saber mais, consulte Aprimoramentos de XMLHttpRequest.

text (o padrão): o tipo de response e responseText é String.

Este exemplo mostra como tratar uma resposta 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;
    });