Abrir arquivos e pastas com um seletorOpen files and folders with a picker

APIs importantesImportant APIs

Acesse arquivos e pastas permitindo que o usuário interaja com um seletor.Access files and folders by letting the user interact with a picker. É possível usar as classes FileOpenPicker e FileSavePicker para obter acesso a arquivos e FolderPicker para obter acesso a uma pasta.You can use the FileOpenPicker and FileSavePicker classes to access files, and the FolderPicker to access a folder.

Observação

 Para obter um exemplo completo, veja o Exemplo de seletor de arquivos. For a complete sample, see the File picker sample.

Pré-requisitosPrerequisites

Interface do usuário do seletor de arquivosFile picker UI

Um seletor de arquivos exibe informações para orientar os usuários e proporcionar uma experiência consistente durante a abertura ou a gravação de arquivos.A file picker displays information to orient users and provide a consistent experience when opening or saving files.

Essas informações incluem:That information includes:

  • A localização atualThe current location
  • O item ou itens que o usuário selecionouThe item or items that the user picked
  • Uma árvore de locais em que o usuário pode navegar.A tree of locations that the user can browse to. Esses locais incluem os locais do sistema de arquivos — como a pasta Músicas ou Downloads — e aplicativos que implementam o contrato do seletor de arquivos (como Câmera, Fotos e 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).

Um aplicativo de email pode exibir um seletor de arquivos para que o usuário selecione anexos.An email app might display a file picker for the user to pick attachments.

um seletor de arquivos com dois arquivos selecionados para abertura.

Como os seletores funcionamHow pickers work

Usando um seletor, o aplicativo pode acessar, procurar e salvar arquivos e pastas no sistema do usuário.With a picker your app can access, browse, and save files and folders on the user's system. Seu aplicativo recebe essas seleções como objetos StorageFile e StorageFolder, nos quais você pode operar em seguida.Your app receives those picks as StorageFile and StorageFolder objects, which you can then operate on.

O seletor usa uma única interface unificada para permitir que o usuário selecione arquivos e pastas no sistema de arquivos ou em outros aplicativos.The picker uses a single, unified interface to let the user pick files and folders from the file system or from other apps. Os arquivos selecionados a partir de outros aplicativos são como arquivos do sistema de arquivos: eles são retornados como objetos StorageFile.Files picked from other apps are like files from the file system: they are returned as StorageFile objects. Em geral, o aplicativo pode operar neles da mesma maneira que em outros objetos.In general, your app can operate on them in the same ways as other objects. Outros aplicativos tornam arquivos disponíveis ao participar de contratos do seletor de arquivos.Other apps make files available by participating in file picker contracts. Se quiser que o aplicativo forneça arquivos, um local de salvamento ou atualizações de arquivos para outros aplicativos, consulte Integrando contratos de seletor de arquivos.If you want your app to provide files, a save location, or file updates to other apps, see Integrating with file picker contracts.

Por exemplo, você pode chamar o seletor de arquivos em seu aplicativo, dessa forma seu usuário poderá abrir um arquivo.For example, you might call the file picker in your app so that your user can open a file. Isso torna seu aplicativo o aplicativo de chamada.This makes your app the calling app. O seletor de arquivos interage com o sistema e/ou com outros aplicativos para permitir que o usuário navegue e selecione o arquivo.The file picker interacts with the system and/or other apps to let the user navigate and pick the file. Quando o usuário escolhe um arquivo, o seletor de arquivos retorna esse arquivo para o seu aplicativo.When your user chooses a file, the file picker returns that file to your app. Aqui está o processo caso em o usuário escolha um arquivo de um aplicativo fornecedor, como OneDrive.Here's the process for the case of the user choosing a file from a providing app, such as OneDrive.

um diagrama que mostra o processo de um aplicativo obtendo um arquivo para abrir em outro aplicativo usando o seletor de arquivos como uma interface entre os dois aplicativos.

Selecionar um arquivo: preencher a listagem de códigosPick 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.";
}

Selecionar um único arquivo: passo a passoPick a single file: step-by-step

Usar um seletor de arquivos envolve criar e personalizar um objeto de seletor de arquivos e mostrar o seletor de arquivos para que o usuário possa selecionar um item ou mais itens.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. Criar e personalizar um 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");
    

    Defina propriedades no objeto do seletor de arquivos relevantes para os usuários e o aplicativo.Set properties on the file picker object relevant to your users and app.

    Este exemplo cria uma exibição visual de qualidade das imagens em um local conveniente que o usuário pode escolher configurando três propriedades: ViewMode, SuggestedStartLocation e 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.

    • A configuração de ViewMode com o valor de enumeração PickerViewMode Thumbnail cria uma exibição visual sofisticada usando miniaturas de imagem para representar arquivos no seletor de arquivos.Setting ViewMode to the PickerViewMode Thumbnail enum value creates a rich, visual display by using picture thumbnails to represent files in the file picker. Faça isso para selecionar arquivos visuais, como imagens ou vídeos.Do this for picking visual files such as pictures or videos. Caso contrário, use PickerViewMode.List.Otherwise, use PickerViewMode.List. Um aplicativo de email hipotético com os recursos Anexar Foto ou Vídeo e Anexar Documento configuraria o ViewMode apropriado para o recurso antes de mostrar o seletor de arquivos.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.

    • Configurar SuggestedStartLocation para Imagens usando PickerLocationId.PicturesLibrary permite que o usuário inicie em um local onde provavelmente encontrará imagens.Setting SuggestedStartLocation to Pictures using PickerLocationId.PicturesLibrary starts the user in a location where they're likely to find pictures. Configure SuggestedStartLocation para um local apropriado para o tipo de arquivo selecionado, como Música, Imagens, Vídeos ou Documentos.Set SuggestedStartLocation to a location appropriate for the type of file being picked, for example Music, Pictures, Videos, or Documents. A partir do local inicial, o usuário pode navegar para outros locais.From the start location, the user can navigate to other locations.

    • Usar FileTypeFilter para especificar tipos de arquivos mantém o usuário focado na seleção dos arquivos relevantes.Using FileTypeFilter to specify file types keeps the user focused on picking files that are relevant. Para substituir os tipos de arquivos anteriores no FileTypeFilter por novas entradas, use ReplaceAll em vez de Add.To replace previous file types in the FileTypeFilter with new entries, use ReplaceAll instead of Add.

  2. Mostrar o FileOpenPickerShow the FileOpenPicker

    • Para selecionar um único arquivoTo 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.";
      }
      
    • Para selecionar vários arquivosTo 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.";
      }
      

Selecionar uma pasta: preencher a listagem de códigosPick 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.";
}

Dica

Sempre que o aplicativo acessar um arquivo ou uma pasta por meio de um seletor, adicione-o a FutureAccessList ou MostRecentlyUsedList do seu aplicativo para rastreá-lo.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. Você pode saber mais sobre o uso dessas listas em Como rastrear arquivos e pastas usados recentemente.You can learn more about using these lists in How to track recently-used files and folders.