Открытие файлов и папок с помощью средства выбораOpen files and folders with a picker

Важные APIImportant APIs

Получите доступ к файлам и папкам, разрешив пользователю взаимодействовать со средством выбора.Access files and folders by letting the user interact with a picker. Для получения доступа к файлам можно использовать классы FileOpenPicker и FileSavePicker, а для получения доступа к папкам — класс FolderPicker.You can use the FileOpenPicker and FileSavePicker classes to access files, and the FolderPicker to access a folder.

Примечание

 Полный пример: пример средства выбора файлов. For a complete sample, see the File picker sample.

Предварительные условияPrerequisites

Пользовательский интерфейс средства выбора файловFile picker UI

В средстве выбора файлов отображаются сведения, позволяющие сориентировать пользователей и обеспечить им привычное взаимодействие с системой при открытии и сохранении файлов.A file picker displays information to orient users and provide a consistent experience when opening or saving files.

Эти сведения включают следующее:That information includes:

  • текущее расположение;The current location
  • выбранный пользователем элемент или несколько элементов;The item or items that the user picked
  • дерево расположений, к которым может перейти пользователь.A tree of locations that the user can browse to. Они включают расположения в файловой системе, например папку «Музыка» или «Загрузки», а также приложения, которые реализуют контракт средства выбора файлов (такие как «Камера», «Фотографии» и Microsoft OneDrive).These locations include file system locations—such as the Music or Downloads folder—as well as apps that implement the file picker contract (such as Camera, Photos, and Microsoft OneDrive).

Почтовое приложение может отображать средство выбора файлов, чтобы предоставить пользователю возможность выбора вложений.An email app might display a file picker for the user to pick attachments.

Средство выбора файлов, в котором выбрано два файла для открытия.

Как работают средства выбораHow pickers work

Используя средство выбора, ваше приложение может получать доступ к файлам и папкам в системе пользователя, просматривать и сохранять их.With a picker your app can access, browse, and save files and folders on the user's system. Ваше приложение получает эти выбранные элементы в виде объектов StorageFile и StorageFolder, с которыми потом можно работать.Your app receives those picks as StorageFile and StorageFolder objects, which you can then operate on.

Средство выбора использует единый унифицированный интерфейс для обеспечения пользователю возможности выбора файлов и папок из файловой системы либо из других приложений.The picker uses a single, unified interface to let the user pick files and folders from the file system or from other apps. Файлы, выбранные из других приложений, воспринимаются как файлы из файловой системы: они возвращаются как объекты StorageFile.Files picked from other apps are like files from the file system: they are returned as StorageFile objects. В целом ваше приложение может работать с ними так же, как с другими объектами.In general, your app can operate on them in the same ways as other objects. Другие приложения обеспечивают доступ к файлам за счет участия в контрактах средства выбора файлов.Other apps make files available by participating in file picker contracts. Сведения о настройке вашего приложения для предоставления другим приложениям файлов, места сохранения или обновлений файлов см. в разделе Взаимодействие с контрактами "Средство выбора файлов".If you want your app to provide files, a save location, or file updates to other apps, see Integrating with file picker contracts.

Например, вы можете вызывать средство выбора файлов в своем приложении, чтобы пользователь имел возможность открыть необходимый файл.For example, you might call the file picker in your app so that your user can open a file. За счет этого ваше приложение становится вызывающим приложением.This makes your app the calling app. Средство выбора файлов взаимодействует с системой и/или другими приложениями, обеспечивая пользователю возможность поиска и выбора определенного файла.The file picker interacts with the system and/or other apps to let the user navigate and pick the file. Когда пользователь выбирает файл, средство выбора файлов возвращает этот файл в ваше приложение.When your user chooses a file, the file picker returns that file to your app. Ниже показан процесс, который имеет место при выборе пользователем файла из другого приложения, например OneDrive.Here's the process for the case of the user choosing a file from a providing app, such as OneDrive.

Схема, на которой одно приложение получает файл для открытия из другого приложения с помощью средства выбора файлов, играющего роль интерфейса между двумя приложениями.

Выбор одного файла: полный кодPick a single file: complete code listing

var picker = new Windows.Storage.Pickers.FileOpenPicker();
picker.ViewMode = Windows.Storage.Pickers.PickerViewMode.Thumbnail;
picker.SuggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.PicturesLibrary;
picker.FileTypeFilter.Add(".jpg");
picker.FileTypeFilter.Add(".jpeg");
picker.FileTypeFilter.Add(".png");

Windows.Storage.StorageFile file = await picker.PickSingleFileAsync();
if (file != null)
{
    // Application now has read/write access to the picked file
    this.textBlock.Text = "Picked photo: " + file.Name;
}
else
{
    this.textBlock.Text = "Operation cancelled.";
}

Выбор одного файла: пошаговые инструкцииPick a single file: step-by-step

Использование средства выбора файлов включает создание и настройку объекта «средство выбора файлов» и отображение средства выбора файлов, чтобы дать пользователю возможность выбрать один или несколько элементов.Using a file picker involves creating and customizing a file picker object, and then showing the file picker so the user can pick one or more items.

  1. Создание и настройка FileOpenPickerCreate and customize a FileOpenPicker

    var picker = new Windows.Storage.Pickers.FileOpenPicker();
    picker.ViewMode = Windows.Storage.Pickers.PickerViewMode.Thumbnail;
    picker.SuggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.PicturesLibrary;
    picker.FileTypeFilter.Add(".jpg");
    picker.FileTypeFilter.Add(".jpeg");
    picker.FileTypeFilter.Add(".png");
    

    Задайте свойства объекта «средство выбора файлов», соответствующие вашим пользователям и приложению.Set properties on the file picker object relevant to your users and app.

    Этот пример создает сложное визуальное отображение в виде картинок в подходящем расположении, которое пользователь может выбрать, установив три свойства: ViewMode, SuggestedStartLocation и FileTypeFilter.This example creates a rich, visual display of pictures in a convenient location that the user can pick from by setting three properties: ViewMode, SuggestedStartLocation, and FileTypeFilter.

    • Задание для свойства ViewMode значения Thumbnail перечисления PickerViewMode создает сложное визуальное представление за счет эскизов изображений, представляющих файлы в средстве выбора файлов.Setting ViewMode to the PickerViewMode Thumbnail enum value creates a rich, visual display by using picture thumbnails to represent files in the file picker. Выполните это, чтобы выбрать визуальные файлы, например фотографии или видео.Do this for picking visual files such as pictures or videos. В других случаях воспользуйтесь PickerViewMode.List.Otherwise, use PickerViewMode.List. Гипотетическое почтовое приложение с функциями Прикрепить изображение или видео и Прикрепить документ установит свойство ViewMode, соответствующее функции, прежде чем отобразить средство выбора файлов.A hypothetical email app with Attach Picture or Video and Attach Document features would set the ViewMode appropriate to the feature before showing the file picker.

    • Выбор библиотеки «Изображения» в качестве значения для параметра SuggestedStartLocation с помощью PickerLocationId.PicturesLibrary позволяет пользователю начать работу в расположении вероятного нахождения изображений.Setting SuggestedStartLocation to Pictures using PickerLocationId.PicturesLibrary starts the user in a location where they're likely to find pictures. Присвойте свойство SuggestedStartLocation расположению, подходящему для типа выбранных файлов, например «Музыка», «Изображения», «Видео» или «Документы».Set SuggestedStartLocation to a location appropriate for the type of file being picked, for example Music, Pictures, Videos, or Documents. Из начального расположения пользователь может перейти в другие расположения.From the start location, the user can navigate to other locations.

    • Использование FileTypeFilter для указания типов файлов сохраняет внимание пользователя на выборе соответствующих файлов.Using FileTypeFilter to specify file types keeps the user focused on picking files that are relevant. Чтобы заменить предыдущие типы файлов в FileTypeFilter новыми записями, используйте вместо метода Add метод ReplaceAll.To replace previous file types in the FileTypeFilter with new entries, use ReplaceAll instead of Add.

  2. Отображение FileOpenPickerShow the FileOpenPicker

    • Выбор одного файлаTo pick a single file

      Windows.Storage.StorageFile file = await picker.PickSingleFileAsync();
      if (file != null)
      {
          // Application now has read/write access to the picked file
          this.textBlock.Text = "Picked photo: " + file.Name;
      }
      else
      {
          this.textBlock.Text = "Operation cancelled.";
      }
      
    • Выбор нескольких файловTo pick multiple files

      var files = await picker.PickMultipleFilesAsync();
      if (files.Count > 0)
      {
          StringBuilder output = new StringBuilder("Picked files:\n");
      
          // Application now has read/write access to the picked file(s)
          foreach (Windows.Storage.StorageFile file in files)
          {
              output.Append(file.Name + "\n");
          }
          this.textBlock.Text = output.ToString();
      }
      else
      {
          this.textBlock.Text = "Operation cancelled.";
      }
      

Выбор папки: полный кодPick a folder: complete code listing

var folderPicker = new Windows.Storage.Pickers.FolderPicker();
folderPicker.SuggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.Desktop;
folderPicker.FileTypeFilter.Add("*");

Windows.Storage.StorageFolder folder = await folderPicker.PickSingleFolderAsync();
if (folder != null)
{
    // Application now has read/write access to all contents in the picked folder
    // (including other sub-folder contents)
    Windows.Storage.AccessCache.StorageApplicationPermissions.
    FutureAccessList.AddOrReplace("PickedFolderToken", folder);
    this.textBlock.Text = "Picked folder: " + folder.Name;
}
else
{
    this.textBlock.Text = "Operation cancelled.";
}

Совет

Каждый раз, когда ваше приложение получает доступ к файлу или папке через средство выбора, добавляйте этот файл или папку в свойство FutureAccessList или MostRecentlyUsedList приложения для отслеживания.Whenever your app accesses a file or folder through a picker, add it to your app's FutureAccessList or MostRecentlyUsedList to keep track of it. Подробнее об использовании этих списков см. в разделе Отслеживание последних использованных файлов и папок.You can learn more about using these lists in How to track recently-used files and folders.