如何使用 WinJS.xhr 下載檔案 (HTML)

發行項
12/11/2015

[ 本文的目標對象是撰寫 Windows 執行階段 App 的 Windows 8.x 和 Windows Phone 8.x 開發人員。如果您正在開發適用於 Windows 10 的 App，請參閱最新文件 ]

WinJS.xhr 讓應用程式可以輕鬆下載網頁內容。這個主題說明如何使用 WinJS.xhr 下載檔案、處理任何錯誤以及報告下載進度，也說明如何下載不同類型的內容。

WinJS.xhr 函式會傳回 WinJS.Promise。如需 JavaScript Promise 中一般及特殊的非同步方法的詳細資訊，請參閱 JavaScript 的非同步程式設計。

警告您現在可以使用 XMLHttpRequest 來傳輸非常大型的物件，例如 Blob 物件和 FormData 物件，不過可能需要一段很長的時間才能完成。因為應用程式可能隨時都會終止，您應該考慮使用 Windows 執行階段 API 的檔案上傳 API 來進行這些操作。如需上傳內容的詳細資訊，請參閱如何上傳檔案。

先決條件

若要完成這個程序，您必須可以使用「適用於 JavaScript 的 Windows Library」範本來建立基本的應用程式。如果建立您的第一個應用程式時需要協助，請參閱使用 JavaScript 建立您的第一個 Windows 執行階段應用程式。

設定您的應用程式用於存取網頁

應用程式必須明確新增特定功能，例如存取網路。如需功能的詳細資訊，請參閱應用程式功能宣告和如何設定網路功能。

在 Visual Studio 中，建立空白的 JavaScript 應用程式。
開啟 package.appxmanifest 檔案，然後移至 [功能] 索引標籤。
如果是 Windows 版的範例，應該已經選取 [網際網路 (用戶端)]**** 功能 (如果尚未選取，請立即選取)。如果應用程式可能需要以用戶端的形式連線到家用或工作網路上的 Web 服務，那麼也需要 [私人網路 (用戶端與伺服器)] 功能。

如果是 Windows Phone 版的範例，請選取 [網際網路 (用戶端與伺服器)]**** 功能。

注意在 Windows Phone，只有一個網路功能 ([網際網路 (用戶端與伺服器)]) 能啟用應用程式的所有網路存取功能。

基本下載

在這個步驟中，您要下載一個網頁並在下載完成時報告。

建立一個空白的應用程式，將它命名為 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" 文字的綠色方塊。
現在試著產生錯誤，看看會發生什麼情況。以 https://www.microsoft.com 取代程式碼中的 URL 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 中，進度函式包含一個代表要求的參數。

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

當您執行程式碼時，在看到內含 "Downloaded the page" 文字的綠色方塊前，會先看到內含 "Ready state is 2" 或 "Ready state is 3" 文字的藍色方塊 (若要看到藍色方塊，您必須在進度函式內部設定中斷點，將速度放慢)。

下載不同類型的內容

您可以使用 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 內容，也就是具有 "text/xml" MIME 類型的內容。如果 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 的資訊：

共用方式為