如何使用 WinJS.xhr 下载文件 (HTML)

项目
12/11/2015

[ 本文适用于编写 Windows 运行时应用的 Windows 8.x 和 Windows Phone 8.x 开发人员。如果你要针对 Windows 10 进行开发，请参阅最新文档 ]

通过 WinJS.xhr 可轻松在你的应用中下载 Web 内容。本主题介绍如何使用 WinJS.xhr 下载文件，处理任何错误以及报告下载的进度。它还介绍了如何下载不同类型的内容。

WinJS.xhr 函数返回 WinJS.Promise。有关常规异步方法以及特殊的 JavaScript Promise 异步方法的详细信息，请参阅使用 JavaScript 异步编程。

警告现在有可能使用 XMLHttpRequest 来传输特别大的对象，如 Blob 对象和 FormData 对象，这可能会花费很长时间才能完成。因为可能会随时终止应用，所以你应该考虑为这些操作在 Windows 运行时 API 中使用文件上载 API。有关上载内容的详细信息，请参阅如何上载文件。

先决条件

若要完成此过程，则需要能够创建一个应用，该应用使用 Windows JavaScript 库模板。有关创建第一个应用的帮助，请参阅创建第一个采用 JavaScript 的 Windows 运行时应用。

设置你的应用以访问 Web

应用需要显式添加特定功能，例如访问网络的功能。有关这些功能的详细信息，请参阅应用功能声明和如何配置网络功能。

在 Visual Studio 中，创建一个空白 JavaScript 应用。
打开 package.appxmanifest 文件并转到“功能”选项卡。
对于该示例的 Windows 版本，应已选中“Internet (客户端)”****功能，但如果尚未选中，则立即进行此操作。如果应用需要作为客户端连接到家庭网络或工作网络上的 Web 服务，则还需要设置“专用网络(客户端和服务器)”功能。

对于示例的 Windows Phone 版本，请选择“Internet (客户端和服务器)”****功能。

注意在 Windows Phone 上，只存在“Internet (客户端和服务器)”这一种网络功能，该功能支持对该应用的所有网络访问。

基本下载

在此步骤中，你将下载一个网页并报告下载完成的时间。

创建空白应用，并将其命名为 XhrExample。
在 default.html 文件的 HTML 正文中，添加一个 DIV 元素以包含完成的通知、进度和错误报告。
```
<div id="xhrReport"></div>
```
此外，还在 default.html 文件的 HTML 正文中添加一个包含 WinJS.xhr 代码的 SCRIPT 元素。
```
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 函数。
构建并以调试模式运行应用。随机将显示一个绿色的框，其中包含“Downloaded the page”语句。
现在，尝试引发错误以便观察即将发生的情况。将代码中的 URL https://www.microsoft.com 替换为 http://www.nosuchsite.example。在调试模式下运行应用时，应该会被带到 WinJS 文件 base.js 中的 terminateAppHandler 函数中的 debugger 声明。

处理错误

在此步骤中，将添加一个发生错误时向 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 函数中提供 progress 函数来报告下载的进度。

向在上一步中添加的代码中添加一个进度处理程序。使用 WinJS.xhr，该 progress 函数具有表示请求的参数。

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

运行代码时，可以看到一个蓝色的框，该框包含“Ready state is 2”或“Ready state is 3”语句，然后你会看到一个绿色的框，该框包含“Downloaded the page”语句（若要看到蓝色框，可能需要在进度函数中设置断点来降低速度）。

下载不同类型的内容

你可以通过使用 WinJS.xhr 下载不同类型的内容。在 WinJS.xhr 的 responseType 选项中指示内容类型。

支持以下类型：

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 文档对象模型 (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;
    });

摘要

你可以在以下主题中找到有关 WinJS.xhr 和 XMLHttpRequest 的详细信息：