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

Artigo
12/12/2015

[ 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 JavaScript

Você pode aprender a escrever aplicativos assíncronas em Guia de início rápido: Usando promessas em JavaScript

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, esta captura de tela mostra um seletor de arquivos que foi chamado para permitir que o usuário selecione alguns arquivos. Na captura de tela, o usuário selecionou dois arquivos. 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.

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.

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

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.

Criar e personalizar um fileOpenPicker

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

O Exemplo de seletor de arquivos demonstra como criar e personalizar um 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"]);
```
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 = Windows.Storage.Pickers.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 = Windows.Storage.Pickers.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.replaceAll 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.replaceAll([".png", ".jpg", ".jpeg"]);
```
  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ê deseja adicionar tipos de arquivo ao fileTypeFilter em vez de substituir entradas, você pode usar o método append em vez do replaceAll.
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
  
  Após criar e personalizar um seletor de arquivos, permita que o usuário selecione um arquivo chamando o fileOpenPicker.pickSingleFileAsync. Quando o usuário seleciona um arquivo, fileOpenPicker.pickSingleFileAsync retorna um objeto storageFile que representa o arquivo escolhido.
  
  A Amostra de seletor de arquivos demonstra como exibir o seletor de arquivos para que o usuário possa selecionar um arquivo, e como capturar o arquivo escolhido para processamento.
```
// 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");
    }
});
```
  Quando a chamada openPicker.pickSingleFileAsync é concluída, o arquivo escolhido que é representado por um objeto storageFile é enviado para uma função literal para ser processado como o parâmetro file. Se a operação foi cancelada e nada foi selecionado, esse parâmetro será null.
- 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 fileOpenPicker.pickMultipleFilesAsync.
  
  Quando o usuário seleciona vários arquivos, fileOpenPicker.pickMultipleFilesAsync retorna uma lista de objetos storageFile que representam os arquivos selecionados.
  
  A Amostra de seletor de arquivos demonstra como exibir o seletor de arquivos para que o usuário possa selecionar vários arquivos, e como capturar a lista de arquivos escolhidos para processamento.
```
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");
    }
});
```
  Quando a chamada openPicker.pickMultipleFilesAsync é concluída, a lista de arquivos selecionados é enviada para uma função literal para processamento como o parâmetro files. Os arquivos selecionados na lista são representados pelos objetos storageFile. Se a operação foi cancelada e nada foi selecionado, esse parâmetro terá um tamanho maior que 0.

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 uma única pasta.

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

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.

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.
```
// 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"]);
```
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 o thumbnail de uma forma parecida com a seguinte:
```
folderPicker.viewMode = Windows.Storage.Pickers.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 = Windows.Storage.Pickers.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.replaceAll 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.replaceAll([".docx", ".xlsx", ".pptx"]);
```
  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.
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 uma pasta chamando folderPicker.pickSingleFolderAsync. Quando o usuário seleciona uma pasta, folderPicker.pickSingleFolderAsync retorna um objeto storageFolder que representa a pasta escolhida. Você deve capturar e processar essa pasta usando done dessa forma, as exceções serão propagadas adequadamente.

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.
```
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");
    }
});
```
Quando a chamada folderPicker.pickSingleFolderAsync é concluída, a pasta selecionada é enviara para uma função literal para processamento como o parâmetro folder. A pasta selecionada é representada por um objeto storageFolder. Se a operação foi cancelada e nada foi selecionado, esse parâmetro será null.

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 à futureAccessList ou à mostRecentlyUsedList do seu aplicativo para rastreá-lo. Para saber mais sobre o uso dessas listas, em Como rastrear arquivos e pastas usados recentemente.

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 mais sobre como trabalhar com arquivos de imagem, consulte Como selecionar e exibir uma imagem, Como decodificar uma imagem e o Exemplo de usar um Blob para salvar e carregar conteúdo.

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.