WinJS.xhr によるファイルのダウンロード方法 (HTML)

[アーティクル]
12/22/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 の使用を検討する必要があります。コンテンツのアップロードについて詳しくは、「ファイルのアップロード方法」をご覧ください。

必要条件

この手順を完了するには、JavaScript 用 Windows ライブラリテンプレートを使った基本的なアプリの作成経験が必要です。初めてのアプリを作る方法について詳しくは、「JavaScript を使った初めての Windows ランタイムアプリの作成」をご覧ください。

Web にアクセスするようにアプリをセットアップする

ネットワークへのアクセスなど、特定の機能を明示的にアプリに追加する必要があります。機能について詳しくは、「アプリ機能の宣言」と「ネットワーク分離機能を構成する方法」をご覧ください。

Visual Studio で空白の JavaScript アプリを作成します。
package.appxmanifest ファイルを開き、[機能] タブに移動します。
Windows バージョンのサンプルでは、[インターネット (クライアント)] 機能は既に選択されています (選択されていない場合はここで選択してください)。アプリがクライアントとしてホームネットワークまたは社内ネットワーク上の Web サービスに接続するには、[プライベートネットワーク (クライアントとサーバー)] 機能も必要です。

Windows Phone バージョンのサンプルの場合は、[インターネット (クライアントとサーバー)] 機能を選びます。

注 Windows Phone では、アプリに対してすべてのネットワークアクセスを有効にするネットワーク機能は [インターネット (クライアントとサーバー)] だけです。

基本的なダウンロード

この手順では、Web ページをダウンロードしたうえで、ダウンロードの完了を報告します。

空のアプリを作り、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 の構文に注目してください。この関数は、オプションを指定できる 1 個のパラメーターを受け取ります。必要なオプションは url だけです。その他のオプションについてはリファレンスドキュメントをご覧ください。

どの promise にも、非同期操作の結果の処理に使う 2 つの関数、then と done があります。どちらの関数も、ダウンロードが完了したとき (つまり、readyState が 4 のとき) に呼び出される関数、エラーが発生したときに呼び出される関数、ダウンロードが進行中のとき (つまり、readyState が 2 または 3 のとき) に呼び出される関数という 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 関数に渡すことによってダウンロードの進行状況を報告します。

前の手順で追加したコードに進行状況ハンドラーを追加します。進行状況関数は 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";
    });

コードを実行すると、"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 について詳しくは、次のトピックをご覧ください。