Cómo descargar un archivo con WinJS.xhr (HTML)

Artículo
12/12/2015

[ Este artículo está destinado a desarrolladores de Windows 8.x y Windows Phone 8.x que escriben aplicaciones de Windows en tiempo de ejecución. Si estás desarrollando para Windows 10, consulta la documentación más reciente

WinJS.xhr proporciona una manera sencilla de descargar contenido web en tu aplicación. En este tema se muestra cómo descargar un archivo con WinJS.xhr, controlar los errores e informar sobre el progreso de la descarga. También se muestra cómo descargar distintos tipos de contenido.

La función WinJS.xhr devuelve un WinJS.Promise. Para más información acerca de métodos asincrónicos en general y compromisos de JavaScript en particular, consulta el tema sobre programación asincrónica en JavaScript.

Advertencia Ahora es posible usar XMLHttpRequest para transferir objetos extremadamente grandes, como objetos Blob y FormData, que probablemente tarden mucho tiempo en completarse. Como las aplicaciones pueden finalizar en cualquier momento, debes considerar la posibilidad de usar las API de carga de archivos en la API de Windows en tiempo de ejecución para estas operaciones. Para obtener más información acerca de la carga de contenido, consulta Cómo cargar un archivo.

Requisitos previos

Para completar este procedimiento, necesitas poder crear una aplicación básica que use la plantilla de la biblioteca de Windows para JavaScript. Si necesitas ayuda para crear tu primera aplicación, consulta Crear la primera aplicación de Windows en tiempo de ejecución con JavaScript.

Configurar tu aplicación para acceder a Internet

Las aplicaciones deben agregar ciertas funcionalidades de manera explícita, como el acceso a la red. Para obtener más información acerca de las funcionalidades, consulta Declaraciones de funcionalidades de aplicación y Cómo configurar las funcionalidades de red.

En Visual Studio, crea una aplicación JavaScript en blanco.
Abre el archivo package.appxmanifest y ve a la pestaña Funcionalidades.
En la versión de Windows del ejemplo, la función Internet (cliente) ya debe estar seleccionada, pero si no lo está, selecciónala ahora. Si la aplicación necesita poder conectarse como cliente a servicios web en una red doméstica o de trabajo, se necesita la función Redes privadas (cliente y servidor).

En la versión de Windows Phone del ejemplo, selecciona la funcionalidad Internet (cliente y servidor).

Nota En Windows Phone, solo hay una funcionalidad de red, Internet (cliente y servidor), que habilita todo el acceso a redes para la aplicación.

Descarga básica

En este paso, descargarás una página web y enviarás una notificación después de descargarla.

Crea una aplicación vacía y asígnale el nombre XhrExample.
En el cuerpo del código HTML del archivo default.html, agrega un elemento DIV para contener los informes de error, progreso y notificación completos.
```
<div id="xhrReport"></div>
```
También debes agregar un elemento SCRIPT que contenga el código WinJS.xhr en el cuerpo del código HTML del archivo default.html.
```
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";
});
```
En el código anterior, la función de finalización escribe en el elemento DIV que se completó la descarga.

Observa la sintaxis de WinJS.xhr. Esta función toma un solo parámetro en el que se especifican las opciones. La única opción obligatoria es url. Puedes leer sobre las otras opciones en la documentación de referencia.

Cada compromiso tiene dos funciones que puedes usar para administrar los resultados de una operación asincrónica, then y done. Ambas funciones toman tres parámetros: una función que se llama al completar la descarga (es decir, cuando readyState es 4), una función que se llama cuando hay un error y una función que se llama cuando la descarga está en curso (cuando readyState es 2 o 3). Solo la función done inicia una excepción si no se controla un error. Debes usar la función done cuando no desees proporcionar una función de error.
Compila y ejecuta la aplicación en modo de depuración. Deberías ver un cuadro verde con la frase "Se descargó la página".
Ahora intenta provocar un error para ver lo que sucede. Reemplaza la dirección URL https://www.microsoft.com del código por http://www.nosuchsite.example. Cuando ejecutes la aplicación en modo de depuración, debería mostrarse la instrucción debugger en la función terminateAppHandler del archivo base.js de WinJS.

Control de errores

En este paso, agregarás un identificador de error que escribirá en el DIV cuando se produzca un error.

Agrega un controlador de errores al código que agregaste en el paso 3. Con WinJS.xhr, la función de error tiene un parámetro que representa la solicitud.

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

Al ejecutar la aplicación, deberías ver un cuadro rojo que notifica el error.

Notificación del progreso

En este paso, notificarás el progreso de la descarga. Para ello, proporcionarás una función de progreso a la función done.

Agrega un controlador de progreso al código que agregaste en el paso anterior. Con WinJS.xhr, la función de progreso tiene un parámetro que representa la solicitud.

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

Al ejecutar el código, deberías ver un cuadro azul con el texto "Estado Listo 2" o "Estado Listo 3" antes de que aparezca el cuadro verde con la frase "Se descargó la página" (es posible que debas ralentizar la tarea con un punto de interrupción para ver el cuadro azul).

Descarga de distintos tipos de contenido

Puedes descargar distintos tipos de contenido usando WinJS.xhr. Indica el tipo de contenido en la opción responseType de WinJS.xhr.

Se admiten los siguientes tipos:

arraybuffer: el tipo de response es ArrayBuffer. Este tipo sirve para representar contenido binario como una matriz de tipo Int8, Int64 u otro tipo entero o flotante. (Consulta el tema sobre matrices con tipo para más información acerca de los distintos tipos de matrices que se admiten actualmente en JavaScript). Las propiedades responseText y responseXML son undefined.

Este código muestra cómo atender una respuesta 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: el tipo de response es Blob. Se usa para representar contenido binario como una sola entidad binaria. Las propiedades responseText y responseXML son undefined.

Este código muestra cómo atender 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: el tipo de response es un objeto Document Object Model (DOM) XML. Se usa para representar contenido XML, es decir, contenido que tiene un tipo MIME "text/xml". Si el tipo MIME no es "text/xml", responseXML es del mismo tipo y responseText es undefined.
json: el tipo de response es String. Se usa para representar cadenas JSON. responseText también es de tipo String y responseXML es undefined.
ms-stream: el tipo de response es msStream, mientras que responseText y responseXML son undefined. Este tipo de respuesta no está definido en la especificación W3C, pero se admite para facilitar la administración de datos de streaming. Para más información, consulta el tema sobre mejoras de XMLHttpRequest.

text (valor predeterminado): el tipo de response y responseText es String.

Este ejemplo muestra cómo atender una respuesta 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;
    });