Idioma: HTML | XAML

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

Applies to Windows and Windows Phone

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.

  1. En Visual Studio, crea una aplicación JavaScript vacía.

  2. Abre el archivo package.appxmanifest y ve a la pestaña Funcionalidades.

  3. En la versión para Windows de la muestra, la funcionalidad Internet (cliente) ya debe estar seleccionada, pero si no lo está, selecciónala ahora. Si es posible que aplicación necesite conectarse como cliente a servicios web en una red doméstica o de trabajo, también se necesita la funcionalidad Redes privadas (cliente y servidor).

    En la versión para Windows Phone de la muestra, 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.

  1. Crea una aplicación vacía y asígnale el nombre XhrExample.

  2. 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>
    
    
  3. 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: "http://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.

  4. 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".

  5. Ahora intenta provocar un error para ver lo que sucede. Reemplaza la dirección URL http://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: "http://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: "http://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: "http://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;
        });
    
    
    

Resumen

Encontrarás más información acerca de WinJS.xhr y XMLHttpRequest en los siguientes temas:

Temas relacionados

Otros recursos
Declaraciones de funcionalidades de aplicación
Conexión a servicios web
Cómo configurar las funcionalidades de red
Cómo crear un mashup con WinJS.xhr
Cómo cargar datos binarios con WinJS.xhr
Establecer valores de tiempo de espera con WinJS.xhr o HttpClient
Referencia
WinJS.xhr
XMLHttpRequest
Mejoras de XMLHttpRequest
Muestras
Integrar contenido y controles de una muestra de servicios web
Muestra de autenticación web

 

 

Mostrar:
© 2014 Microsoft