言語: HTML | XAML

クイック スタート: ファイル ピッカーによるファイルへのアクセス (JavaScript と HTML を使った Windows ランタイム アプリ)

Applies to Windows and Windows Phone

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

必要条件

ファイル ピッカーの UI

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

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

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

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

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

ファイル ピッカーの左上にある場所のドロップダウン リスト部分の画面。

 

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

ファイル ピッカーのサンプルでは、fileOpenPicker を使って、ユーザーが 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 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 つのファイルを選ぶ場合のチュートリアル

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

  1. ファイル ピッカーを呼び出せることを確認する

    ファイル ピッカーを呼び出そうとするたびに、まず、アプリがファイル ピッカーを表示できることを確認する必要があります。そのためには、アプリがスナップされていないことを確認します (スナップされている場合は、ファイル ピッカーを表示するためにスナップを解除します)。

    ファイル ピッカーのサンプルでは、アプリの ApplicationView.value をチェックする方法と、サンプルがファイル ピッカーを作成して表示する前にスナップの解除を試す方法を説明しています。

    
    // 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;
    }
    
    
    

    警告  アプリがスナップされているときに、ファイル ピッカーを表示しようとすると、呼び出しに失敗し、例外が発生します。

  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 をカスタマイズする理由

    ファイル ピッカーのサンプルでは、fileOpenPickerviewModesuggestedStartLocationfileTypeFilter という 3 つのプロパティを設定して、使いやすい場所に画像の視覚的に優れた表示を作成し、そこでユーザーがファイルを選べるようにします。

    • openPicker.viewModethumbnail PickerViewMode 列挙値に設定すると、ファイル ピッカーでファイルを表すために画像の縮小表示が使われて、視覚的に優れた表示が作成されます。

      
      openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
      
      

      画像や動画のような視覚的なファイルを表示するためにファイル ピッカーを使う場合は、viewModePickerViewMode.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 メソッドを使うことができます。

  3. 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 つのフォルダーを選ぶ場合のチュートリアル

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

  1. ファイル ピッカーを呼び出せることを確認する

    ファイル ピッカーを呼び出そうとするたびに、まず、アプリがファイル ピッカーを表示できることを確認する必要があります。そのためには、アプリがスナップされていないこと (スナップされている場合は、ファイル ピッカーを表示するためにスナップを解除できること) を確認します。

    ファイル ピッカーのサンプルでは、アプリの ApplicationView.value をチェックする方法と、サンプルがファイル ピッカーを作成して表示する前にスナップの解除を試す方法を説明しています。

    
    // 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;
    }
    
    
    

    警告  アプリがスナップされているときに、ファイル ピッカーを表示しようとすると、呼び出しに失敗し、例外が発生します。

  2. 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 プロパティ (viewModesuggestedStartLocationfileTypeFilter) を使って、ファイルを選ぶためのファイル ピッカーをカスタマイズしています。

    • folderPicker.viewMode の既定の PickerViewMode.list を使うと、ファイル ピッカーに一覧のような表示を作成できます。この一覧は、文書のような、あまり視覚的ではないファイルを選ぶ場合に適しています。

      画像や動画のような視覚的なファイルを表示するためにファイル ピッカーを使う場合は、viewModePickerViewMode.thumbnail に設定することを検討するようにお勧めします。それ以外の場合は、PickerViewMode.list を使います。

      画像や動画のような視覚的なファイルを表示する場合は、次のように、folderPicker.viewModethumbnail に設定します。

      
      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 を使って画像のインポート元の場所を選ぶときに、画像ファイルが表示されれば、その場所を選んだ場合にインポートされる項目を特定しやすくなります。

  3. ユーザーが 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 を使ってコンテンツの保存と読み込みを行うサンプルをご覧ください。

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

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

関連トピック

ファイル ピッカーのサンプル
ファイル アクセスのサンプル
Blob を使ってコンテンツの保存と読み込みを行うサンプルに関するページ
ファイル ピッカーのガイドラインとチェック リスト
ファイル ピッカーでファイルを保存する方法
最近使ったファイルやフォルダーを追跡する方法
クイック スタート: ファイルの読み取りと書き込み
画像の選択方法と表示方法
クイック スタート: ファイル ピッカーによるサービスの提供
辞書/リファレンス
Windows.Storage.Pickers namespace
Windows.Storage.Pickers.fileOpenPicker class
Windows.Storage.Pickers.folderPicker class
Windows.Storage.Pickers.pickerLocationId enum
Windows.Storage.Pickers.pickerViewMode enum

 

 

表示:
© 2014 Microsoft