Início Rápido: acessando arquivos com seletores de arquivos
Idioma: HTML | XAML

Guia de início rápido: acessando arquivos com seletores de arquivos (XAML)

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

Acesse arquivos e pastas por meio do seletor de arquivos permitindo que os usuários selecionem arquivos e pastas. Você pode usar a classe FileOpenPicker para obter acesso a arquivos e FolderPicker para obter acesso a pastas.

Pré-requisitos

Entender a programação assíncrona dos aplicativos do Tempo de Execução do Windows em C++, C# ou Visual Basic

Você pode aprender a escrever aplicativos assíncronos em Guia de início rápido: chamando APIs assíncronas em C# ou Visual Basic.

interface do usuário do seletor de arquivos

Os seletores de arquivos têm áreas na parte superior e inferior da tela que exibem informações, orientam os usuários e fornecem uma experiência consistente quando usuários acessam ou salvam arquivos.

As informações exibidas incluem:

  • O local atual, que fica na parte superior esquerda.
  • Uma cesta de itens para escolha do usuário, que fica na parte inferior
  • Uma lista suspensa de locais onde o usuário pode navegar, que pode ser selecionada clicando no circunflexo invertido, na parte esquerda superior.

Por exemplo, essa captura de tela mostra um seletor de arquivos que foi chamado por um aplicativo de email para permitir que o usuário escolha algumas fotos (na captura de tela, o usuário não selecionou qualquer foto).

Uma captura de tela do seletor de arquivos com dois arquivos selecionados para serem abertos.

O usuário pode exibir a lista suspensa de locais disponíveis, como a lista mostrada na captura de tela à direita, selecionando o circunflexo invertido na parte superior esquerda do seletor de arquivos. Esses locais incluem os locais do sistema de arquivos, como a pasta Músicas ou Downloads. Eles também incluem outros aplicativos, quando esses outros aplicativos (como o Microsoft OneDrive) participam de contratos de seletor de arquivo, que você pode ver na parte inferior da lista na captura de tela.

Um recorte da captura de tela do seletor de arquivos que mostra a lista suspensa de locais na parte superior esquerda.

 

Como os seletores de arquivos funcionam

Por meio do seletor de arquivos, seu aplicativo pode obter acesso aos arquivos e pastas em todo o sistema do usuário. Quando você chama o seletor de arquivos, o usuário pode navegar em seu sistema e selecionar arquivos (ou pastas) para acessar e salvar. Depois que o usuário seleciona os arquivos ou pastas, seu aplicativo recebe essas seleções como objetos StorageFile e StorageFolder. Com isso, seu aplicativo pode operar nos arquivos e pastas selecionados usando esses objetos. Para saber mais sobre como acessar arquivos, veja Acesso ao arquivo e permissões.

O seletor de arquivos usa uma única interface unificada para permitir que o usuário selecione arquivos e pastas no sistema de arquivos ou em outros aplicativos. Os arquivos selecionados a partir de outros aplicativos são como arquivos do sistema de arquivos: eles são retornados como objetos StorageFile. Em geral, seu aplicativo pode operar neles da mesma maneira que em outros objetos. Outros aplicativos tornam arquivos disponíveis ao participar de contratos do seletor de arquivos. Se você desejar que seu aplicativo forneça arquivos por meio do seletor de arquivos, poderá saber mais em Integrando com contratos do seletor de arquivos.

Por exemplo, você pode chamar o seletor de arquivos em seu aplicativo, dessa forma seu usuário poderá abrir um arquivo. Isso torna seu aplicativo o aplicativo de chamada. O seletor de arquivos interage com o sistema e com outros aplicativos para permitir que o usuário navegue e selecione o arquivo. Quando o usuário escolhe um arquivo, o seletor de arquivos retorna esse arquivo para o seu aplicativo. O diagrama ilustra esse processo, no caso em que o usuário escolhe um arquivo em outro aplicativo como o OneDrive. Nesse caso, o OneDrive é o aplicativo de fornecimento.

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.

Código completo para selecionar um arquivo

O Exemplo de seletor de arquivos demonstra como usar o FileOpenPicker para permitir que o usuário selecione um único arquivo.


FileOpenPicker openPicker = new FileOpenPicker();
openPicker.ViewMode = PickerViewMode.Thumbnail;
openPicker.SuggestedStartLocation = PickerLocationId.PicturesLibrary;
openPicker.FileTypeFilter.Add(".jpg");
openPicker.FileTypeFilter.Add(".jpeg");
openPicker.FileTypeFilter.Add(".png");

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


Para obter o código completo para selecionar vários arquivos, consulte o Exemplo de seletor de arquivos.

Guia passo a passo para selecionar um arquivo

Chamar o seletor de arquivos exige duas tarefas básicas: 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 itens.

  1. Criar e personalizar um FileOpenPicker

    Use o FileOpenPicker se o usuário estiver selecionando arquivos. Você pode personalizar esta classe definindo propriedades no objeto criado.

    O exemplo de seletor de arquivos demonstra como criar e personalizar um FileOpenPicker.

    
    FileOpenPicker openPicker = new FileOpenPicker();
    openPicker.ViewMode = PickerViewMode.Thumbnail;
    openPicker.SuggestedStartLocation = PickerLocationId.PicturesLibrary;
    openPicker.FileTypeFilter.Add(".jpg");
    openPicker.FileTypeFilter.Add(".jpeg");
    openPicker.FileTypeFilter.Add(".png");
    
    
    

    Você deverá definir as propriedades no objeto do seletor de arquivos que forem relevantes para seus usuários e seu aplicativo. Para obter diretrizes para ajudá-lo a decidir como personalizar o seletor de arquivos, consulte Diretrizes e lista de verificação para os seletores de arquivos. Para obter explicações do motivo pelo qual definimos determinadas propriedades para personalizar os seletores de arquivos no Exemplo de seletor de arquivos, continue lendo.

    Personalizações do FileOpenPicker do exemplo do seletor de arquivos, explicadas

    O Exemplo de seletor de arquivos cria uma exibição visual rica e imagens em um local conveniente que o usuário pode selecionar definindo três propriedades do FileOpenPicker : ViewMode, SuggestedStartLocation e FileTypeFilter.

    • A definição do openPicker.ViewMode para o valor de enumeração Thumbnail PickerViewMode cria uma exibição visual rica usando miniaturas de imagem para representar os arquivos do seletor de arquivos.

      
      openPicker.ViewMode = PickerViewMode.Thumbnail;
      
      

      Você deve considerar a definição do ViewMode para PickerViewMode.Thumbnail se você estiver usando o seletor de arquivos para exibir arquivos visuais como imagens ou vídeos. Caso contrário, use PickerViewMode.List.

      Em alguns casos, o usuário pode desejar selecionar uma imagem ou vídeo ou qualquer outro tipo de arquivo. Por exemplo, o usuário pode selecionar um arquivo para anexar a um email ou para enviar por IM. Neste caso, você deve dar suporte aos dois modos de exibição adicionando dois controles de interface do usuário a seu aplicativo. Um controle deve chamar o seletor de arquivos usando o modo de exibição Thumbnail, dessa forma o usuário pode selecionar imagens e vídeos. O outro controle deve chamar o seletor de arquivos usando o modo de exibição List, dessa forma o usuário pode selecionar outros tipos de arquivos. Por exemplo, um aplicativo de email teria dois botões: Anexar Imagem ou Vídeo e Anexar Documento.

    • Definindo o openPicker.SuggestedStartLocation para Imagens usando o PickerLocationId.PicturesLibrary permite que o usuário inicie em um local onde provavelmente encontrará imagens.

      
      openPicker.SuggestedStartLocation = PickerLocationId.PicturesLibrary;
      
      

      Você deve definir o SuggestedStartLocation para o local do sistema de arquivos que seja adequado para o tipo de arquivo que está sendo selecionado. Se o usuário estiver selecionando música, imagens ou vídeos, defina o local inicial para Músicas, Imagens ou Vídeos, respectivamente. Para todos os outros tipos de arquivos, defina o local inicial como Documentos. Este é apenas um local inicial. Os usuários podem navegar para outros locais enquanto usam o seletor de arquivos.

      Além disso, o SuggestedStartLocation não é sempre usado como o local inicial para o seletor de arquivos. Para dar ao usuário uma sensação de consistência, o seletor de arquivos lembra o último local que o usuário visualizou e geralmente iniciará naquele local.

    • Usar o openPicker.FileTypeFilter.Add para especificar os tipos de arquivos que o usuário pode ver no seletor de arquivos nos permite manter o usuário concentrado nos arquivos de seleção que são relevantes e utilizáveis.

      
      openPicker.FileTypeFilter.Add(".jpg");
      openPicker.FileTypeFilter.Add(".jpeg");
      openPicker.FileTypeFilter.Add(".png");
      
      

      Para C#:   O Add é o nome do método Append para desenvolvedores de C#.

      Você deve considerar a especificação dos tipos de arquivos para exibir no seletor de arquivos para ajudar a manter os arquivos que são exibidos relevantes. Por exemplo, se o seu aplicativo for um player de vídeo, você poderá usar a propriedade FileTypeFilter para assegurar que os arquivos exibidos no seletor de arquivos estejam nos formatos de vídeo que seu player aceita, com base na extensão do nome do arquivo de vídeo.

      Se você desejar substituir os tipos anteriores de arquivos no FileTypeFilter com novas entradas, poderá usar o método ReplaceAll em vez do Add.

  2. Mostrar o FileOpenPicker

    Agora você pode mostrar o seletor de arquivos, dessa forma o usuário pode selecionar um ou vários arquivos:

    • Mostrar de forma que o usuário possa selecionar um único arquivo

      Depois de criar e personalizar um seletor de arquivos, permita que o usuário selecione um arquivo chamando await no FileOpenPicker.PickSingleFileAsync.

      Quando o usuário selecionar um arquivo, FileOpenPicker.PickSingleFileAsync retorna um objeto StorageFile que representa o arquivo selecionado.

      O exemplo de seletor de arquivos demonstra como exibir o seletor de arquivos para permitir que o usuário selecione um arquivo.

      
      StorageFile file = await openPicker.PickSingleFileAsync();
      if (file != null)
      {
          // Application now has read/write access to the picked file
          OutputTextBlock.Text = "Picked photo: " + file.Name;
      }
      else
      {
          OutputTextBlock.Text = "Operation cancelled.";
      }
      
      
      
    • Mostrar de forma que o usuário possa selecionar vários arquivos

      Depois de criar e personalizar um seletor de arquivos, permita que o usuário selecione vários arquivos chamando await no FileOpenPicker.PickMultipleFilesAsync.

      Quando o usuário seleciona vários arquivos, o FileOpenPicker.PickMultipleFilesAsync retorna uma lista de arquivos selecionados. Os arquivos da lista são representados pelos objetos StorageFile.

      O Exemplo de seletor de arquivos demonstra como exibir o seletor de arquivos para que o usuário possa escolher vários arquivos, e como capturar a lista de arquivos escolhidos para processamento.

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

Código completo para selecionar uma pasta

O Exemplo de seletor de arquivos demonstra como usar o FolderPicker para permitir que o usuário selecione um único arquivo.


if (rootPage.EnsureUnsnapped())
{
    FolderPicker folderPicker = new FolderPicker();
    folderPicker.SuggestedStartLocation = PickerLocationId.Desktop;
    folderPicker.FileTypeFilter.Add(".docx");
    folderPicker.FileTypeFilter.Add(".xlsx");
    folderPicker.FileTypeFilter.Add(".pptx");

    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)
        StorageApplicationPermissions.FutureAccessList.AddOrReplace("PickedFolderToken", folder);
        OutputTextBlock.Text = "Picked folder: " + folder.Name;
    }
    else
    {
        OutputTextBlock.Text = "Operation cancelled.";
    }
}


Para obter o código completo para selecionar vários arquivos, veja o Exemplo de seletor de arquivos.

Guia passo a passo para selecionar uma pasta

Chamar o seletor de arquivos exige duas tarefas básicas: 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 itens.

  1. Criar e personalizar um FolderPicker

    Use o FolderPicker se o usuário estiver selecionando uma pasta. Você pode personalizar esta classe definindo propriedades no objeto criado.

    O exemplo de seletor de arquivos demonstra como criar e personalizar um FolderPicker.

    
    FolderPicker folderPicker = new FolderPicker();
    folderPicker.SuggestedStartLocation = PickerLocationId.Desktop;
    folderPicker.FileTypeFilter.Add(".docx");
    folderPicker.FileTypeFilter.Add(".xlsx");
    folderPicker.FileTypeFilter.Add(".pptx");
    
    
    

    Você deverá definir as propriedades no objeto do seletor de arquivos que forem relevantes para seus usuários e seu aplicativo. Para obter diretrizes para ajudá-lo a decidir como personalizar o seletor de arquivos, consulte Diretrizes e lista de verificação para os seletores de arquivos. Para obter explicações do motivo pelo qual definimos determinadas propriedades para personalizar os seletores de arquivos no Exemplo de seletor de arquivos , continue lendo.

    Personalizações do FolderPicker do exemplo do seletor de arquivos, explicadas

    O Exemplo do seletor de arquivos personaliza o seletor de arquivos para selecionar pastas usando três propriedades do FolderPicker: ViewMode, SuggestedStartLocation e FileTypeFilter.

    • Usando o PickerViewMode.List padrão para o folderPicker.ViewMode nos permite criar uma exibição parecida com uma lista no seletor de arquivos. Esta lista é boa para selecionar arquivos que não muito visuais, como documentos.

      Você deve considerar a definição do ViewMode para PickerViewMode.Thumbnail se você estiver usando o seletor de arquivos para exibir arquivos visuais como imagens ou vídeos. Caso contrário, use PickerViewMode.List.

      Se você estiver exibindo os arquivos visuais como imagens ou vídeos, deverá definir o folderPicker.ViewMode para Thumbnail de uma forma parecida com a seguinte:

      
      folderPicker.ViewMode = PickerViewMode.Thumbnail;
      
      
    • Definir o folderPicker.SuggestedStartLocation para o desktop do usuário usando o PickerLocationId.Desktop permite que o usuário inicie em um local familiar e bastante usado.

      
      folderPicker.SuggestedStartLocation = PickerLocationId.Desktop;
      
      

      Você deve definir o SuggestedStartLocation para o local do sistema de arquivos que é adequado para o tipo de pasta que o usuário deseja selecionar. Por exemplo, se o usuário estiver selecionando uma pasta que contém arquivos de música, você deverá iniciá-los em Músicas. Esse é apenas um local de início; os usuários podem navegar para outros locais enquanto usam o seletor de arquivos.

      Além disso, o SuggestedStartLocation não é sempre usado como o local inicial para o seletor de arquivos. Para dar ao usuário uma sensação de consistência, o seletor de arquivos lembra o último local que o usuário visualizou e geralmente iniciará naquele local.

    • Usar o folderPicker.FileTypeFilter.Add para especificar os tipos de arquivos que o usuário pode ver no seletor de arquivos nos permite manter o usuário concentrado na seleção de uma pasta relevante.

      
      folderPicker.FileTypeFilter.Add(".docx");
      folderPicker.FileTypeFilter.Add(".xlsx");
      folderPicker.FileTypeFilter.Add(".pptx");
      
      
      Observação   O Add é o método Append visto que ele é projetado para os desenvolvedores de C#.
       

      Os usuários podem selecionar apenas as pastas por meio de um FolderPicker, eles não poderão selecionar arquivos individuais. Entretanto, mostrar arquivos relevantes no FolderPicker ajuda os usuários a determinarem qual pasta eles desejam selecionar. Por exemplo, ao usar o FolderPicker para selecionar um local de onde importar imagens, mostrar os arquivos de imagem ajuda o usuário a identificar quais itens serão importados quando o local for selecionado.

  2. Mostrar o FolderPicker de forma que o usuário pode selecionar uma única pasta

    Depois que você criar e personalizar um FolderPicker, permita que o usuário selecione um arquivo chamando await no FolderPicker.PickSingleFolderAsync.

    Quando o usuário seleciona uma pasta, FolderPicker.PickSingleFolderAsync retorna um objeto StorageFolder que representa a pasta escolhida.

    O Exemplo de seletor de arquivos demonstra como exibir o seletor de arquivos para que o usuário possa selecionar uma pasta e como capturar a pasta escolhida para processamento.

    
    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)
        StorageApplicationPermissions.FutureAccessList.AddOrReplace("PickedFolderToken", folder);
        OutputTextBlock.Text = "Picked folder: " + folder.Name;
    }
    else
    {
        OutputTextBlock.Text = "Operation cancelled.";
    }
    
    
    

Resumo e próximas etapas

Caso você use um código semelhante ao que mostramos, o seu aplicativo deverá exibir um seletor de arquivos para permitir que os usuários selecionem um ou mais arquivos ou pastas que o seu aplicativo poderá abrir.

Dica  Sempre que o aplicativo acessar um arquivo ou uma pasta por meio do seletor de arquivos, adicione esse item à FutureAccessListou à MostRecentlyUsedList do seu aplicativo para rastreá-lo. Você pode saber mais sobre como usar essas listas em Como rastrear arquivos e pastas recentemente usados.
 

Para saber mais sobre leitura e gravação de arquivos, veja Guia de início rápido: lendo e gravando um arquivo e o Exemplo de acesso de arquivo. Para saber sobre como trabalhar com arquivos de imagem, veja Guia de Início Rápido: Imagem e ImageBrush, Guia de Início Rápido: Geração de Imagens e o Exemplo de imagem XAML.

Se quiser mais informações sobre como chamar o seletor de arquivos para salvar arquivos, veja Como salvar arquivos usando seletores de arquivos.

Se quiser que o aplicativo forneça arquivos, um local de salvamento ou atualizações de arquivos para outros aplicativos, veja Guia de início rápido: Integrando contratos de seletor de arquivos.

Tópicos relacionados

Exemplo de seletor de arquivos
Exemplo de acesso a arquivos
Exemplo de imagem XAML
Diretrizes e lista de verificação dos seletores de arquivos
Como salvar arquivos usando seletores de arquivos
Como rastrear arquivos e pastas usados recentemente
Guia de início rápido: Lendo e gravando um arquivo
Guia de Início Rápido: Image e ImageBrush
Guia de Início Rápido: Geração de Imagens
Acesso e permissões de arquivo
Guia de início rápido: Integrando contratos de seletor de arquivos
Referência de namespace
Windows.Storage.Pickers namespace
Windows.Storage.Pickers.FileOpenPicker class
Windows.Storage.Pickers.FolderPicker class
Windows.Storage.Pickers.PickerLocationId enum
Windows.Storage.Pickers.PickerViewMode enum

 

 

Mostrar:
© 2017 Microsoft