Guia de início rápido: acessando arquivos de forma programática (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 que estão em um local específico, como uma pasta, biblioteca, dispositivo ou local de rede. Você também pode consultar arquivos e pastas em um local por meio de consultas de arquivo e pasta.

Pré-requisitos

Entender a programação assíncrona dos aplicativos do Tempo de Execução do Windows em JavaScript

É possível aprender a escrever aplicativos assíncronos em Guia de início rápido: usando promessas em JavaScript.
Acessar permissões ao local

Por exemplo, o código nesses exemplos exige a funcionalidade de biblioteca Imagens, mas o local talvez exija outra funcionalidade ou até mesmo nenhuma funcionalidade. Para obter mais informações, veja Acesso e permissões de arquivo. Para saber mais sobre como usar o seletor de arquivos para acessar arquivos e pastas, consulte Guia de início rápido: acessando arquivos com seletores de arquivos.

Enumerar arquivos e pastas de nível superior em um local

Obtenha uma StorageFolder que represente o local.

Se quiser obter uma lista do conteúdo de uma determinada pasta, primeiro obtenha o objeto StorageFolder, que representa esse local.

O Exemplo de enumeração de pasta como obter a biblioteca de Imagens:
```
var picturesLibrary = Windows.Storage.KnownFolders.picturesLibrary;
```
No exemplo anterior, usamos KnownFolders para obter a biblioteca de Imagens (como um objeto StorageFolder). Você pode usar propriedades KnownFolders para obter pastas que representam um número de recursos do usuário como bibliotecas, dispositivos ou locais de rede.

Importante Se você quer usar uma propriedade KnownFolders para acessar uma biblioteca, um dispositivo ou um local de rede, o seu aplicativo deve ter o recurso correspondente em seu manifesto de aplicativo. Para saber mais sobre o acesso a arquivo e recursos, veja Acesso a arquivo e permissões e Acesso a recursos do usuário usando o Tempo de Execução do Windows.
Obtenha uma lista do conteúdo da pasta.

O Exemplo de enumeração de pasta demonstra como obter a biblioteca Imagens:
```
picturesLibrary.getItemsAsync().then(function (items) {
```
Conforme apresentado no exemplo anterior, você pode chamar getItemsAsync() para obter uma lista de todos os conteúdos da pasta (um StorageFolder objeto). Se você não deseja todos os itens, é possível chamar getItemsAsync(startIndex, maxItemsToRetrieve) para obter o conteúdo da pasta de forma simples, pelo índice.

Quando você chama um método getItemsAsync em uma pasta, a lista de itens recebidos é limitada aos arquivos e subpastas nesta pasta e não inclui arquivos e pastas contidos nas subpastas.

Se você deseja uma lista dos arquivos em uma pasta, é possível chamar um método getFilesAsync. Se você deseja uma lista de pastas, é possível chamar um método getFoldersAsync.

Use then após obter a operação para definir uma função que considera a lista de objetos que você recebe, items no exemplo anterior e execute as tarefas adicionais que você precisa.
Trabalhe com a sua lista.

O Exemplo de enumeração de pasta demonstra como executar tarefas adicionais com a lista de items na biblioteca Imagens:
```
    outputHeader(picturesLibrary.name, items.size);
    items.forEach(function (item) { 
        if (item.isOfType(Windows.Storage.StorageItemTypes.folder)) { 
            output(id(picturesLibrary.name), item.name + "\\"); 
        } 
        else { 
            output(id(picturesLibrary.name), item.fileName); 
        } 
    });
```
O exemplo anterior passa o name da pasta e o size da lista para uma função auxiliar que exibe essa informação ao usuário.

Você também pode iterar na lista de itens para executar tarefas adicionais, conforme apresentado no exemplo anterior. Você também pode chamar forEach na lista de itens para iterar através de itens na lista. A função que você passa para forEach deve considerar um item da lista como um argumento, e será executado para cada item na lista.

Você pode processar cada item posteriormente, chamando os métodos nos mesmos individualmente. No exemplo anterior, determinamos se um item é uma pasta objeto (StorageFolder) ou um arquivo (objeto StorageFile) , comparando o resultado do método isOfType, presente nos arquivos e pastas, com valor enum StorageItemTypes. Usamos essa comparação para passar diferentes informações sobre o item para a função auxiliar output, mas você também pode executar algumas tarefas adicionais.

Para obter mais contexto e ver como as funções outputHeader e output funcionam, baixe Exemplo de enumeração de pasta.

Quando tiver concluído, o código terá uma aparência semelhante a esta:


// Get folder
var picturesLibrary = Windows.Storage.KnownFolders.picturesLibrary;

//  Get folder contents
picturesLibrary.getItemsAsync().then(function (items) {
    // Then perform tasks with the list of files and folders that was retrieved

    // For example, display name of containing folder and count of items in folder
    outputHeader(picturesLibrary.name, items.size);

    // For example, display info for each item
    items.forEach(function (item) { 
        if (item.isOfType(Windows.Storage.StorageItemTypes.folder)) { 
            output(id(picturesLibrary.name), item.name + "\\"); 
        } 
        else { 
            output(id(picturesLibrary.name), item.fileName); 
        } 
    }); 
});

Consultar arquivos em um local

Obtenha a pasta continente.

Se quiser obter uma lista do conteúdo de uma pasta específica, você precisará primeiro obter a pasta.

O Exemplo de enumeração de pasta como obter a biblioteca Imagens:
```
var picturesLibrary = Windows.Storage.KnownFolders.picturesLibrary;
```
No exemplo anterior, usamos KnownFolders para obter a biblioteca de Imagens (como um objeto StorageFolder). Você pode usar propriedades KnownFolders para obter pastas que representam um número de recursos do usuário como bibliotecas, dispositivos ou locais de rede.

Importante Se você quer usar uma propriedade KnownFolders para acessar uma biblioteca, um dispositivo ou um local de rede, o seu aplicativo deve ter o recurso correspondente em seu manifesto de aplicativo. Para saber mais sobre o acesso a arquivo e recursos, veja Acesso a arquivo e permissões e Acesso a recursos do usuário usando o Tempo de Execução do Windows.
Crie uma consulta de pasta para organizar os arquivos que especificar.

Ao criar uma consulta em uma pasta, os arquivos nessa pasta e respectivas subpastas serão organizados em grupos, de acordo com os seus critérios. Os grupos de resultados são pastas virtuais que têm toda a funcionalidade de uma pasta no sistema de arquivos, permitindo-lhe obter e processar os arquivos no seu interior quando necessário.

O Exemplo de enumeração de pasta demonstra como criar uma consulta de pasta que agrupa imagens na biblioteca de Imagens no mês que foram tiradas ou criadas:
```
var query = picturesLibrary.createFolderQuery(Windows.Storage.Search.CommonFolderQuery.groupByMonth);
```
Conforme mostrado no exemplo anterior, você pode chamar createFolderQuery(query) na sua pasta para criar uma consulta de pastas (um objeto StorageFolderQueryResult) a fim de organizar os arquivos nessa pasta e subpastas nas pastas virtuais no valor CommonFolderQuery que você especificar. No exemplo, escolhemos agrupar os arquivos de imagens na pasta picturesLibrary, dentro das pastas virtuais com base no mês (CommonFolderQuery.groupByMonth) em que a imagem foi tirada ou criada.

Você também pode criar consultas de pastas, chamando createFolderQuery() ou createFolderQueryWithOptions.
Obtenha a lista de pastas virtuais na consulta.

O exemplo FolderEnumeration na home page de exemplo do aplicativo usa query para obter a lista de pastas virtuais:
```
query.getFoldersAsync().then(function (monthList) {
    monthList.forEach(function (month) { 
```
Como mostrado no exemplo anterior, você pode chamar getFoldersAsync() na consulta de pastas para obter uma lista das pastas virtuais. Use then para definir uma função que processa sua lista. No exemplo, nossa consulta devolve uma lista de pastas virtuais que representam os meses, monthList e nós processamos nossa lista chamando monthList.forEach e definindo uma função para processar cada pasta month.
Obtenha a lista de arquivos na pasta virtual.

O Exemplo de enumeração de pasta demonstra como usar a pasta month para obter a lista de imagens que foram tiradas ou criadas no mês:
```
        var tempMonthName = month.name; 
        month.getFilesAsync().then(function (files) {
```
Dica É possível que você precise armazenar informações sobre a pasta virtual (month) de forma que você possa usá-la mais tarde. No exemplo anterior, armazenamos o nome de nossa pasta virtual (month.name)em tempMonthName de forma que possamos usá-la quando processamos nossa lista de imagens (files).

Use then para definir uma função que processa a lista de arquivos que você recebe.

Quando tiver concluído, o código terá uma aparência semelhante a esta:


// Get folder
var picturesLibrary = Windows.Storage.KnownFolders.picturesLibrary; 

// Create query
var query = picturesLibrary.createFolderQuery(Windows.Storage.Search.CommonFolderQuery.groupByMonth); 

// Get virtual folders from query
query.getFoldersAsync().then(function (monthList) { 
    monthList.forEach(function (month) {
 
        var tempMonthName = month.name;
        // Get files from virtual folder 
        month.getFilesAsync().then(function (files) { 
            // Then perform tasks with retrieved files
        }); 
    }); 
});