クイックスタート: ファイルピッカーによるファイルへのアクセス (HTML)

[アーティクル]
12/22/2015

[ この記事は、Windows ランタイムアプリを作成する Windows 8.x および Windows Phone 8.x 開発者を対象としています。Windows 10 向けの開発を行っている場合は、「最新のドキュメント」をご覧ください]

ファイルピッカーでユーザーがファイルやフォルダーを選べるようにして、ファイルやフォルダーにアクセスします。ファイルには fileOpenPicker クラスを使ってアクセスでき、フォルダーには folderPicker を使ってアクセスできます。

必要条件

JavaScript を使った Windows ランタイムアプリの非同期プログラミングについての理解

非同期アプリの作成方法については、「クイックスタート: JavaScript での promise の使用」をご覧ください。

ファイルピッカーの UI

ファイルピッカーは画面の上下に情報表示領域があり、ユーザーへの指示が表示され、ユーザーがファイルにアクセスまたは保存するときの一貫したエクスペリエンスを提供します。

次のような情報が表示されます。

現在の場所 (左上に表示される)
ユーザーが選んだ項目のバスケット (下端に表示される)
ユーザーが参照できる場所のドロップダウンリスト (左上の下向きキャレットから選ぶことができる)

たとえば、次のスクリーンショットは、ユーザーがファイルを選べるように呼び出されたファイルピッカーを示しています。スクリーンショットでは、ユーザーが 2 つのファイルを選んでいます。 2 つのファイルが開く対象として選ばれているファイルピッカーの画面。

ユーザーがファイルピッカーの左上にある下向きキャレットを選ぶと、右側のスクリーンショットで示されているリストのような、利用できる場所のドロップダウンリストが表示されます。これらの場所には、ミュージックフォルダーやダウンロードフォルダーのような、ファイルシステムの場所も含まれます。また、スクリーンショットのリストの下部に示されているように、ファイルピッカーコントラクトに参加しているアプリ (Microsoft OneDrive など) があれば、それらのアプリも含まれます。

1 つのファイルを選ぶ完全なコード

ファイルピッカーのサンプルでは、fileOpenPicker を使って、ユーザーが 1 つのファイルを選べるようにする方法を示しています。

// Create the picker object and set options
var openPicker = new Windows.Storage.Pickers.FileOpenPicker();
openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.picturesLibrary;
// Users expect to have a filtered view of their folders depending on the scenario.
// For example, when choosing a documents folder, restrict the filetypes to documents for your application.
openPicker.fileTypeFilter.replaceAll([".png", ".jpg", ".jpeg"]);

// Open the picker for the user to pick a file
openPicker.pickSingleFileAsync().then(function (file) {
    if (file) {
        // Application now has read/write access to the picked file
        WinJS.log && WinJS.log("Picked photo: " + file.name, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});

複数のファイルを選ぶ場合の完全なコードについては、ファイルピッカーのサンプルをご覧ください。

1 つのファイルを選ぶ場合のチュートリアル

ファイルピッカーの呼び出しには、2 つの基本的なタスクが必要です。それらは、ファイルピッカーオブジェクトの作成とカスタマイズ、ユーザーが項目を選ぶためのファイルピッカーの表示です。

fileOpenPicker を作成してカスタマイズする

ユーザーが 1 つまたは複数のファイルを選ぶ場合は、fileOpenPicker を使います。作成するオブジェクトでプロパティを設定することによって、このクラスをカスタマイズできます。

ファイルピッカーのサンプルでは、fileOpenPicker の作成とカスタマイズの方法が示されています。
```
// Create the picker object and set options
var openPicker = new Windows.Storage.Pickers.FileOpenPicker();
openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.picturesLibrary;
// Users expect to have a filtered view of their folders depending on the scenario.
// For example, when choosing a documents folder, restrict the filetypes to documents for your application.
openPicker.fileTypeFilter.replaceAll([".png", ".jpg", ".jpeg"]);
```
ファイルピッカーオブジェクトの、ユーザーとアプリに関連するプロパティを設定する必要があります。ファイルピッカーのカスタマイズ方法を判断するためのガイドラインについては、「ファイルピッカーのガイドラインとチェックリスト」をご覧ください。ファイルピッカーのサンプルで特定のプロパティを設定してファイルピッカーをカスタマイズする理由については、後で説明します。

ファイルピッカーのサンプルで fileOpenPicker をカスタマイズする理由

ファイルピッカーのサンプルでは、fileOpenPicker の viewMode、suggestedStartLocation、fileTypeFilter という 3 つのプロパティを設定して、使いやすい場所に画像の視覚的に優れた表示を作成し、そこでユーザーがファイルを選べるようにします。
- openPicker.viewMode を thumbnail PickerViewMode 列挙値に設定すると、ファイルピッカーでファイルを表すために画像の縮小表示が使われて、視覚的に優れた表示が作成されます。
```
openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
```
  画像やビデオのような視覚的なファイルを表示するためにファイルピッカーを使う場合は、viewMode を PickerViewMode.thumbnail に設定することを検討するようにお勧めします。それ以外の場合は、PickerViewMode.list を使います。
  
  場合によっては、ユーザーが画像やビデオだけでなく、他の種類のファイルも選びたいことがあります。たとえば、電子メールに添付したり、IM で送信したりするファイルを選ぶ場合です。この場合は、アプリに 2 つの UI コントロールを追加して、両方の表示モードをサポートする必要があります。1 つのコントロールでは、ユーザーが画像やビデオを選べるように、thumbnail 表示モードを使ってファイルピッカーを呼び出します。もう 1 つのコントロールでは、ユーザーが他の種類のファイルを選べるように、list 表示モードを使ってファイルピッカーを呼び出します。たとえば、メールアプリには、[画像またはビデオの添付] と [ドキュメントの添付] という 2 つのボタンを用意します。
- openPicker.suggestedStartLocation を、PickerLocationId.picturesLibrary を使って Pictures に設定すると、画像を見つけられる可能性が高い場所が最初に表示されます。
```
openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.picturesLibrary;
```
  suggestedStartLocation は、選択されるファイルの種類に適したファイルシステム上の場所に設定する必要があります。ユーザーが音楽、画像、またはビデオを選ぶ場合は、最初に表示する場所をそれぞれミュージック、ピクチャ、ビデオに設定します。他の種類のファイルの場合は、最初に表示する場所をドキュメントに設定します。これは単なる開始場所です。ユーザーはファイルピッカーを使って、別の場所に移動できます。
  
  また、suggestedStartLocation は、常にファイルピッカーで最初に表示される場所として使われるとは限りません。ユーザーに対する一貫性を保つために、ファイルピッカーはユーザーが表示した最後の場所を記憶しておき、通常はその場所を最初に表示します。
- openPicker.fileTypeFilter.replaceAll を使って、ユーザーがファイルピッカーで見ることができるファイルの種類を指定すると、関連があって使用できるファイルだけをユーザーの選択対象にすることができます。
```
openPicker.fileTypeFilter.replaceAll([".png", ".jpg", ".jpeg"]);
```
  適切なファイルだけが表示されるように、ファイルピッカーに表示するファイルの種類を指定することを検討してください。たとえば、アプリがビデオプレーヤーである場合、fileTypeFilter プロパティを使うと、ビデオのファイル名拡張子に基づいて、プレーヤーでサポートされているビデオ形式のファイルだけをファイルピッカーに表示できます。
  
  エントリを置き換えるのではなく、ファイルの種類を fileTypeFilter に追加したい場合は、replaceAll ではなく append メソッドを使うことができます。
fileOpenPicker を表示する

これで、ユーザーが 1 つのファイルまたは複数のファイルを選べるように、ファイルピッカーを表示できます。
- ユーザーが 1 つのファイルを選べるように表示する
  
  ファイルピッカーを作り、カスタマイズしたら、fileOpenPicker.pickSingleFileAsync を呼び出してユーザーが 1 つのファイルを選べるようにします。ユーザーがファイルを選ぶと、fileOpenPicker.pickSingleFileAsync から、選択されたファイルを表す storageFile オブジェクトが返されます。
  
  ファイルピッカーのサンプルでは、ファイルピッカーを表示してユーザーが 1 つのファイルを選べるようにする方法と、選択されたファイルを処理のためにキャプチャする方法を説明します。
```
// Open the picker for the user to pick a file
openPicker.pickSingleFileAsync().then(function (file) {
    if (file) {
        // Application now has read/write access to the picked file
        WinJS.log && WinJS.log("Picked photo: " + file.name, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});
```
  openPicker.pickSingleFileAsync の呼び出しが完了すると、選択されたファイル (storageFile オブジェクトで表される) が、処理のために file パラメーターとして関数リテラルに渡されます。操作が取り消され、何も選ばれなかった場合、このパラメーターは null になります。
- ユーザーが複数のファイルを選べるように表示する
  
  ファイルピッカーを作り、カスタマイズしたら、fileOpenPicker.pickMultipleFilesAsync を呼び出してユーザーが複数のファイルを選べるようにします。
  
  ユーザーが複数のファイルを選ぶと、fileOpenPicker.pickMultipleFilesAsync から、選択されたファイルを表す storageFile オブジェクトの一覧が返されます。
  
  ファイルピッカーのサンプルでは、ファイルピッカーを表示してユーザーが複数のファイルを選べるようにする方法と、選択されたファイルの一覧を処理のためにキャプチャする方法を示しています。
```
openPicker.pickMultipleFilesAsync().then(function (files) {
    if (files.size > 0) {
        // Application now has read/write access to the picked file(s)
        var outputString = "Picked files:\n";
        for (var i = 0; i < files.size; i++) {
            outputString = outputString + files[i].name + "\n";
        }
        WinJS.log && WinJS.log(outputString, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});
```
  openPicker.pickMultipleFilesAsync の呼び出しが完了すると、選択されたファイルの一覧が、処理のために files パラメーターとして関数リテラルに渡されます。一覧内の選ばれたファイルは、storageFile オブジェクトで表されます。操作が取り消され、何も選ばれなかった場合、このパラメーターのサイズは 0 より大きくなります。

1 つのフォルダーを選ぶ完全なコード

ファイルピッカーのサンプルでは、folderPicker を使って、ユーザーが 1 つのフォルダーを選べるようにする方法を示しています。

// Verify that we are currently not snapped, or that we can unsnap to open the picker
var currentState = Windows.UI.ViewManagement.ApplicationView.value;
if (currentState === Windows.UI.ViewManagement.ApplicationViewState.snapped &&
    !Windows.UI.ViewManagement.ApplicationView.tryUnsnap()) {
    // Fail silently if we can't unsnap
    return;
}

// Create the picker object and set options
var folderPicker = new Windows.Storage.Pickers.FolderPicker;
folderPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.desktop;
// Users expect to have a filtered view of their folders depending on the scenario.
// For example, when choosing a documents folder, restrict the filetypes to documents for your application.
folderPicker.fileTypeFilter.replaceAll([".docx", ".xlsx", ".pptx"]);

folderPicker.pickSingleFolderAsync().then(function (folder) {
    if (folder) {
        // Application now has read/write access to all contents in the picked folder (including sub-folder contents)
        // Cache folder so the contents can be accessed at a later time
        Windows.Storage.AccessCache.StorageApplicationPermissions.futureAccessList.addOrReplace("PickedFolderToken", folder);
        WinJS.log && WinJS.log("Picked folder: " + folder.name, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});

1 つのフォルダーを選ぶ場合のチュートリアル

folderPicker を作成してカスタマイズする

ユーザーがフォルダーを選ぶ場合は、folderPicker を使います。作成するオブジェクトでプロパティを設定することによって、このクラスをカスタマイズできます。

ファイルピッカーのサンプルでは、folderPicker の作成とカスタマイズの方法が示されています。
```
// Create the picker object and set options
var folderPicker = new Windows.Storage.Pickers.FolderPicker;
folderPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.desktop;
// Users expect to have a filtered view of their folders depending on the scenario.
// For example, when choosing a documents folder, restrict the filetypes to documents for your application.
folderPicker.fileTypeFilter.replaceAll([".docx", ".xlsx", ".pptx"]);
```
ファイルピッカーオブジェクトの、ユーザーとアプリに関連するプロパティを設定する必要があります。ファイルピッカーのカスタマイズ方法を判断するためのガイドラインについては、「ファイルピッカーのガイドラインとチェックリスト」をご覧ください。ファイルピッカーのサンプルで特定のプロパティを設定してファイルピッカーをカスタマイズする理由については、後で説明します。

ファイルピッカーのサンプルで folderPicker をカスタマイズする理由

ファイルピッカーのサンプルでは、3 つの folderPicker プロパティ (viewMode、suggestedStartLocation、fileTypeFilter) を使って、ファイルを選ぶためのファイルピッカーをカスタマイズしています。
- folderPicker.viewMode の既定の PickerViewMode.list を使うと、ファイルピッカーに一覧のような表示を作成できます。この一覧は、文書のような、あまり視覚的ではないファイルを選ぶ場合に適しています。
  
  画像やビデオのような視覚的なファイルを表示するためにファイルピッカーを使う場合は、viewMode を PickerViewMode.thumbnail に設定することを検討するようにお勧めします。それ以外の場合は、PickerViewMode.list を使います。
  
  画像やビデオのような視覚的なファイルを表示する場合は、次のように、folderPicker.viewMode を thumbnail に設定します。
```
folderPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
```
- folderPicker.suggestedStartLocation を、PickerLocationId.desktop を使ってユーザーのデスクトップに設定すると、よく使う慣れた場所が最初に表示されます。
```
folderPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.desktop;
```
  suggestedStartLocation は、ユーザーが選択するフォルダーの種類に適したファイルシステム上の場所に設定する必要があります。たとえば、音楽ファイルが含まれているフォルダーをユーザーが選ぶ場合は、ミュージックが最初に表示されるようにします。これは単なる開始場所であり、ユーザーはファイルピッカーを使って、別の場所に移動できます。
  
  また、suggestedStartLocation は、常にファイルピッカーで最初に表示される場所として使われるとは限りません。ユーザーに対する一貫性を保つために、ファイルピッカーはユーザーが表示した最後の場所を記憶しておき、通常はその場所を最初に表示します。
- folderPicker.fileTypeFilter.replaceAll を使って、ユーザーがファイルピッカーで見ることができるファイルの種類を指定すると、関連があるフォルダーだけをユーザーの選択対象にすることができます。
```
folderPicker.fileTypeFilter.replaceAll([".docx", ".xlsx", ".pptx"]);
```
  ユーザーは、folderPicker を通じてフォルダーだけを選ぶことができ、個々のファイルは選べません。ただし、関連するファイルが folderPicker に表示されれば、どのフォルダーを選べばよいかが判断しやすくなります。たとえば、folderPicker を使って画像のインポート元の場所を選ぶときに、画像ファイルが表示されれば、その場所を選んだ場合にインポートされる項目を特定しやすくなります。
ユーザーが 1 つのフォルダーを選べるように folderPicker を表示する

folderPicker を作り、カスタマイズしたら、folderPicker.pickSingleFolderAsync を呼び出して、ユーザーが 1 つのフォルダーを選べるようにします。ユーザーがフォルダーを選ぶと、folderPicker.pickSingleFolderAsync から、選択されたフォルダーを表す storageFolder が返されます。例外が適切に伝達されるように、このフォルダーを、done を使ってキャプチャして処理する必要があります。

ファイルピッカーのサンプルでは、ファイルピッカーを表示してユーザーが 1 つのフォルダーを選べるようにする方法と、選択されたフォルダーを処理のためにキャプチャする方法を説明します。
```
folderPicker.pickSingleFolderAsync().then(function (folder) {
    if (folder) {
        // Application now has read/write access to all contents in the picked folder (including sub-folder contents)
        // Cache folder so the contents can be accessed at a later time
        Windows.Storage.AccessCache.StorageApplicationPermissions.futureAccessList.addOrReplace("PickedFolderToken", folder);
        WinJS.log && WinJS.log("Picked folder: " + folder.name, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});
```
folderPicker.pickSingleFolderAsync の呼び出しが完了すると、選ばれたフォルダーが、処理のために folder パラメーターとして関数リテラルに渡されます。選ばれたフォルダーは storageFolder オブジェクトで表されます。操作が取り消され、何も選ばれなかった場合、このパラメーターは null になります。

要約と次のステップ

ここで示したものと同じようなコードを使うと、アプリはファイルピッカーを表示し、ユーザーが選んだ 1 つまたは複数のファイルまたはフォルダーを開けるようになります。

ヒント アプリがファイルピッカーでファイルまたはフォルダーにアクセスするたびに、その項目をアプリの futureAccessList または mostRecentlyUsedList に追加して、項目を追跡します。これらのリストの使用について詳しくは、「最近使ったファイルやフォルダーを追跡する方法」をご覧ください。

ファイルの読み取りと書き込みについて詳しくは、「クイックスタート: ファイルの読み取りと書き込み」と、ファイルアクセスのサンプルをご覧ください。画像ファイルの操作について詳しくは、「画像の選択方法と表示方法」、「画像をデコードする方法」と、Blob を使ってコンテンツの保存と読み込みを行うサンプルをご覧ください。

ファイルピッカーを呼び出してファイルを保存する方法について詳しくは、「ファイルピッカーでファイルを保存する方法」をご覧ください。

ファイル、保存場所、またはファイルの更新を他のアプリに提供する場合は、「クイックスタート: ファイルピッカーコントラクトとの統合」をご覧ください。

クイックスタート: ファイルピッカーによるファイルへのアクセス (HTML)

必要条件

ファイルピッカーの UI

1 つのファイルを選ぶ完全なコード

1 つのファイルを選ぶ場合のチュートリアル

1 つのフォルダーを選ぶ完全なコード

1 つのフォルダーを選ぶ場合のチュートリアル

要約と次のステップ

関連トピック

その他のリソース

クイック スタート: ファイル ピッカーによるファイルへのアクセス (HTML)

必要条件

ファイル ピッカーの UI

1 つのファイルを選ぶ完全なコード

1 つのファイルを選ぶ場合のチュートリアル

1 つのフォルダーを選ぶ完全なコード

1 つのフォルダーを選ぶ場合のチュートリアル

要約と次のステップ

関連トピック

その他のリソース

クイックスタート: ファイルピッカーによるファイルへのアクセス (HTML)

ファイルピッカーの UI