Скачивание файла с помощью WinJS.xhr (HTML)

Статья
12/12/2015

[ Эта статья адресована разработчикам приложений среды выполнения Windows для Windows 8.x и Windows Phone 8.x. При разработке приложений для Windows 10 см. раздел последняя документация]

С помощью WinJS.xhr можно легко скачивать веб-содержимое в ваше приложение. В этом разделе показано, как скачать файл с помощью WinJS.xhr, обработать любые ошибки, а также продемонстрировать ход выполнения скачивания. Кроме того, здесь рассказывается, как скачивать различные типы содержимого.

Функция WinJS.xhr возвращает WinJS.Promise. Подробнее об асинхронных методах в целом и объектах Promise в JavaScript в частности: Асинхронное программирование на JavaScript.

Предупреждение Теперь можно использовать XMLHttpRequest для переноса очень больших объектов, таких как объекты Blob и FormData, выполнение которых может занять много времени. Поскольку работа приложений может прерваться в любой момент, следует рассмотреть возможность использования для этих операций API отправки файлов в API среды выполнения Windows. Подробнее об отправке содержимого: Как отправить файл.

Необходимые условия

Для выполнения этой процедуры вам нужно уметь создать базовые приложения, использующие шаблон библиотеки Windows для JavaScript. Подробнее о создании первого приложения: Создание первого приложения среды выполнения Windows на JavaScript.

Настройка доступа приложения к Интернету

Некоторые возможности, такие как доступ к сети, необходимо добавлять в приложения отдельно. Подробнее о возможностях см. в разделах Объявления возможностей приложений и Как настроить возможности сетевого подключения.

В Visual Studio создайте пустое приложение JavaScript.
Откройте файл Package.appxmanifest и выберите вкладку Возможности.
Для версии примера для Windows возможность Интернет (клиент) должна быть уже выбрана, но если это не сделано, выберите ее. Если приложению может понадобиться возможность подключаться от имени клиента к веб-службам в домашней или рабочей сети, то также потребуется возможность Частные сети (клиент и сервер).

Для версии примера для Windows Phone выберите возможность Интернет (клиент и сервер).

Примечание В Windows Phone имеется только один тип возможности сетевого подключения — Интернет (клиент и сервер). Он обеспечивает приложению все формы доступа к сети.

Простое скачивание

На этом этапе вы скачиваете веб-страницу и создаете сообщение об окончании скачивания.

Создайте пустое приложение и назовите его XhrExample.
Добавьте элемент DIV, содержащий уведомление о завершении, сообщение о ходе выполнения и сообщение об ошибке, в тело кода в файле default.html.
```
<div id="xhrReport"></div>
```
Также добавьте в тело кода в файле default.html элемент SCRIPT, содержащий код 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";
});
```
В приведенном выше коде функция complete создает в элементе DIV запись о завершении скачивания.

Обратите внимание на синтаксис WinJS.xhr. Эта функция принимает единственный параметр, в котором можно указать различные атрибуты. Единственный обязательный атрибут — url. О других атрибутах можно узнать из справочной документации.

Каждый объект Promise имеет две функции, которые можно использовать для обработки результатов асинхронной операции, — then и done. Обе функции принимают три параметра: функцию, которая вызывается по окончании скачивания (то есть когда readyState равно 4), функцию, которая вызывается в случае ошибки, и функцию, которая вызывается в ходе скачивания (то есть когда readyState равно 2 или 3). Только функция done выдает исключение, если ошибка не обработана. Вы должны использовать функцию done, когда вы не хотите предоставлять функцию ошибки.
Создайте и запустите приложение в режиме отладки. Вы увидите зеленое поле со словами "Страница скачана".
Теперь попробуйте вызвать ошибку и посмотрите, что произойдет. Замените URL-адрес https://www.microsoft.com в коде на http://www.nosuchsite.example. При запуске приложения в режиме отладки вы должны перейти к оператору debugger в функции terminateAppHandler в файле WinJS base.js.

Обработка ошибок

На этом шаге вы добавите обработчик ошибок, который создает запись в элементе DIV при возникновении ошибки.

Добавьте обработчик ошибок в код, который вы добавили выше на этапе 3. При использовании WinJS.xhr функция ошибки имеет параметр, представляющий запрос.

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

После запуска приложения появится красное поле с сообщением об ошибке.

Сообщение о ходе выполнения

На этом этапе вы создадите сообщение о ходе скачивания, добавив функцию хода выполнения в функцию done.

Добавьте обработчик хода выполнения в код, который вы добавили на предыдущем этапе. При использовании WinJS.xhr функция хода выполнения имеет параметр, представляющий запрос.
```
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";
    });
```
После запуска кода появится синее поле со словами "Состояние готовности 2" или "Состояние готовности 3", а затем появится зеленое поле со словами "Страница скачана". (Чтобы увидеть синее поле, необходимо замедлить выполнение задания с помощью точки останова.)

Скачивание разных типов содержимого

С помощью WinJS.xhr вы можете скачивать содержимое различных типов. Тип содержимого указывается в параметре responseType метода WinJS.xhr.

При этом поддерживаются следующие типы.

arraybuffer: тип response — ArrayBuffer. Этот тип используется для представления двоичного содержимого в виде массива типа Int8, Int64 либо другого типа массива целых чисел или чисел с плавающей запятой. (Подробнее о различных типовых массивах, в настоящее время поддерживаемых JavaScript, см. в разделе Типовые массивы.) Свойства responseText и responseXML — undefined.

В данном примере кода показано, как обрабатывать отклик 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: тип response — Blob. Используется для представления двоичного содержимого как единого двоичного объекта. Свойства responseText и responseXML — undefined.

В данном примере кода показано, как обрабатывать 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: данный тип response является объектом XML модели DOM. Используется для представления содержимого XML, т. е. содержимого, имеющего тип MIME "text/xml". Если тип MIME отличается от "text/xml", то responseXML будет такого же типа, а responseText будет типа undefined.
json: тип response — String. Используется для представления строк JSON. responseText также будет типа String, а responseXML будет типа undefined.
ms-stream: тип response msStream, а responseText и responseXML — undefined. Данный тип отклика не определен в спецификации консорциума W3C, однако поддерживается для упрощения управления потоковой передачей данных. Подробнее: Улучшения объекта XMLHttpRequest.

text (по умолчанию): тип response и responseText являются String.

В данном примере кода показано, как управлять откликом 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;
    });