Manipulação de arquivos, do início ao fim

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

Saiba como adicionar os recursos de manipulação de arquivos ao seu aplicativo da Windows Store usando JavaScript e executando no Windows 8.1.

Cada seção deste tópico descreve um recurso principal de manipulação de arquivos, vincula para um tópico que fornece mais detalhes sobre esse recurso e oferece informações sobre como encontrar rapidamente o código relevante no exemplo complementar deste tópico. Exemplo complementar de manipulação de arquivos, do início ao fim.

Observação  Muitos das funções usadas para interagir com pastas e arquivos são assíncronos. Você pode saber como escrever aplicativos JavaScript assíncronos em Programação assíncrona em JavaScript.

 

Noções básicas de acesso a arquivos: enumeração, obtenção de propriedades e leitura e gravação de dados

	Guia de início rápido: Acessando arquivos de forma programática Você pode acessar arquivos em um local, como uma pasta, uma biblioteca, um dispositivo ou um local da rede, com apenas uma única linha de código — uma chamada para a função StorageFolder.getFilesAsync. Veja Acessando arquivos de forma programática para instruções passo a passo que ilustram como realizar tarefas como enumerar arquivos e pastas de nível superior de um local especificado e consultar arquivos em um local. Essas etapas mostram como enumerar arquivos em um local específico: Obtenha um objeto StorageFolder para o local que deseja. Por exemplo, você pode fazer isso ao referenciar uma das propriedades KnownFolders estáticas, como KnowFolders.picturesLibrary. Chame a função StorageFolder do objeto StorageFolder.getFilesAsync retornado. O exemplo auxiliar desse tópico chama esse método sem qualquer parâmetro, indicando se todos os arquivos devem ser retornados. Para ver exemplos de chamada StorageFolder.getFilesAsync com uma consulta, consulte Início rápido: acessando arquivos de forma programática. Quando a função StorageFolder.getFilesAsync estiver concluída, você pode usar um loop forEach para iterar em cada arquivo retornado. Esse exemplo de código enumera todos os arquivos em Imagens. // Get a StorageFolder object representing Pictures. var library = Windows.Storage.KnownFolders.picturesLibrary; // Get all files from the StorageFolder object. library.getFilesAsync().then(function (files) { // For each file found ... files.forEach(function (file) { // ... perform your processing. }); }); } Essa captura de tela do exemplo auxiliar mostra um exemplo de enumeração dos arquivos em Imagens. Encontre no exemplo: o exemplo inclui uma página intitulada FileAccessBasics, que inclui os exemplos apresentados nesta seção. O código JavaScript e HTML relevante está centralizado nos arquivos FileAccessBasicsPage.js (função OnEnumPicturesClick) e FileAccessBasicsPage.html.
	Guia de início rápido: obtendo as propriedades de um arquivo As propriedades de arquivo descrevem ou quantificam um atributo de um arquivo ou o seu conteúdo. Por exemplo, as propriedades de arquivo incluem esses dados como nome do arquivo, caminho, tamanho do arquivo, atributos de arquivo e data de último acesso. O Guia de início rápido: obtendo as propriedades de um arquivo mostra como recuperar e exibir as propriedades de nível superior e básicas de um arquivo. Essas etapas mostram como obter propriedades de nível superior ou básicas de um arquivo: Propriedades de nível superior do arquivo — Você recupera as propriedades básicas do arquivo como as propriedades da classe StorageFile. Elas incluem StorageFile.attributes, StorageFile.contentType, StorageFile.dateCreated, StorageFile.displayName, StorageFile.displayType, StorageFile.fileType, StorageFile.folderRelativeId, StorageFile.isAvailable, StorageFile.name, StorageFile.path, e StorageFile.provider. (O Guia de início rápido: determinando disponibilidade dos arquivos do Microsoft OneDrive explica como usar StorageFile.isAvailable.) Propriedades básicas do arquivo — Você recupera as propriedades básicas de um arquivo chamando a função StorageFile.getBasicPropertiesAsync que retorna um objeto BasicProperties que você pode usar para recuperar propriedades do arquivo, como BasicProperties.dateModified, BasicProperties.itemDate e BasicProperties.size. Esse exemplo de código enumera todos os arquivos em Imagens e exibe várias propriedades básicas e de nível superior do arquivo. Observe como as promises de JavaScript estão sendo usadas para sincronizar os resultados de duas operações assíncronas (StorageFolder.getFilesAsync e StorageFile.getBasicPropertiesAsync). Para saber mais sobre a programação assíncrona e promises em JavaScript, consulte Programação assíncrona em JavaScript. // Get a StorageFolder object representing the Pictures Library. var library = Windows.Storage.KnownFolders.picturesLibrary; // Initialize string that holds all property information. var outString = ""; // Get all files from the StorageFolder object. library.getFilesAsync().then(function (files) { var promises = []; files.forEach(function (file) { promises.push(WinJS.Promise.as(file)); promises.push(file.getBasicPropertiesAsync()); }) return WinJS.Promise.join(promises); }) .done(function (results) { var counter = 0 while (counter < results.length) { var file = results[counter]; var props = results[counter + 1]; outString += "File name: " + file.name + "<br/>"; outString += "File type: " + file.fileType + "<br/>"; outString += "File size: " + props.size + "<br/>"; outString += "<br/>" counter = counter + 2; } }); Essa captura de tela do exemplo complementar mostra um exemplo de várias propriedades de arquivo básicas e de nível superior. Encontre no exemplo: o exemplo inclui uma página intitulada FileAccessBasics, que inclui os exemplos apresentados nesta seção. O código JavaScript e HTML relevante está centralizado nos arquivos FileAccessBasicsPage.js (função (OnGetFilePropertiesClick) e FileAccessBasicsPage.html.
	Guia de início rápido: lendo e gravando um arquivo Um aplicativo da Windows Store lê e grava arquivos por meio da classe FileIO. Veja Guia de início rápido: lendo e gravando um arquivo para exemplos de código que mostram como ler e gravar vários tipos de dados usando as classes FileIO e StorageFile. Gravando texto em um arquivo Para gravar em um arquivo, você primeiro precisa adquirir um objeto StorageFile para passar para uma das funções FileIO para gravação de dados. Na amostra de acompanhamento, isso é feito ao criar um arquivo através da função StorageFolder.createFileAsync. Depois que tiver um objeto StorageFile, você pode gravar texto no arquivo subjacente através de uma das funções FileIO.writeTextAsync sobrecarregadas. Esse exemplo de código grava a data/hora atual em um arquivo de exemplo. // Create the sample file; replacing it if it already exists. var lib = Windows.Storage.KnownFolders.picturesLibrary; lib.createFileAsync("FileHandlingJs.txt", Windows.Storage.CreationCollisionOption.replaceExisting) .then(function (file) { if (file) { // Format a string based on the current data/time. var now = new Date(); var sampleFileContents = [[now.getMonth() + 1, now.getDate(), now.getFullYear()].join("/"), [now.getHours(), AddZero(now.getMinutes())].join(":"), now.getHours() >= 12 ? "PM" : "AM"].join(" "); // Write the text to the sample file. Windows.Storage.FileIO.writeTextAsync(file, sampleFileContents) .then(function () { // File's contents have been written at this point. }, function (error) { // Handle error. }); } }); Lendo texto de um arquivo Para ler o conteúdo de um arquivo, você primeiro precisa adquirir um objeto StorageFile para passar para uma das funções FileIO para leitura de dados. Na amostra de acompanhamento, isso é feito ao chamar a função StorageFolder.getFileAsync. Após criar um objeto StorageFile, você pode ler o texto no arquivo subjacente através de uma das funções FileIO.readTextAsync sobrecarregadas. Este exemplo de código lê o conteúdo de um arquivo de amostra. // Open sample file. Windows.Storage.KnownFolders.picturesLibrary.getFileAsync("FileHandlingJs.txt") .then(function (file) { // If file found ... if (file) { // Read file's contents. Windows.Storage.FileIO.readTextAsync(file).then(function (contents) { // Process file contents as needed. }); } }, function (error) { // Handle error. }); Essa captura de tela mostra um exemplo da execução do exemplo e da gravação no arquivo de exemplo. Encontre no exemplo: o exemplo inclui uma página intitulada FileAccessBasics, que inclui os exemplos apresentados nesta seção. O código JavaScript e HTML relevante está centralizado nos arquivos FileAccessBasicsPage.js (funções OnWriteTextToFileClick e OnReadTextFromFileClick) e FileAccessBasicsPage.html.

 

Trabalhando com seletores de arquivo e pasta

Guia de início rápido: acessando arquivos com seletores de arquivos Seletores — de arquivos e de pastas — são usados para exibir uma lista de arquivos/pastas, da qual o usuário pode selecionar um ou mais itens para processamento adicional. Os seletores podem ser configurados de forma programática para procurar arquivos e pastas que correspondem a um filtro especificado (como arquivos com extensões específicas), iniciar em uma pasta determinada, exibir um modo de exibição específico (lista ou miniatura) e muito mais. Os procedimentos a seguir mostram como configurar os vários seletores para seleção de um único arquivo, vários arquivos e uma única pasta. Configurando um seletor de arquivo de seleção de arquivo único Instancie um objeto FileOpenPicker. Defina o FileOpenPicker do objeto viewMode, suggestedStartLocation e as propriedades de fileTypeFilter conforme necessário. Chame a função FileOpenPicker.pickSingleFileAsync. Quando a função FileOpenPicker.pickSingleFileAsync estiver concluída, o aplicativo possui acesso de leitura/gravação ao arquivo selecionado. Este exemplo de código instancia e mostra um seletor de arquivo para uma seleção de arquivo único. // Instantiate a FileOpenPicker object. var openPicker = new Windows.Storage.Pickers.FileOpenPicker(); // Set the FileOpenPicker object's key properties. openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail; openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.picturesLibrary; openPicker.fileTypeFilter.replaceAll([".jpg", ".jpeg", ".png" ]); // Display the FileOpenPicker for single file selection. openPicker.pickSingleFileAsync().then(function (file) { // If the user selected a file ... if (file) { // ... process file as needed. } else { // User canceled the operation. } }); Configurando um seletor de arquivo de seleção de vários arquivos Instancie um objeto FileOpenPicker. Defina o FileOpenPicker do objeto FileOpenPicker.viewMode, FileOpenPicker.suggestedStartLocation e as propriedades de FileOpenPicker.FileTypeFilter conforme necessário. Chame a função FileOpenPicker.pickMultipleFileAsync. Quando a função FileOpenPicker.pickMultipleFileAsync estiver concluída, o aplicativo possui acesso de leitura/gravação aos arquivos selecionados. Os arquivos selecionados são representados por uma matriz de objetos StorageFile. A propriedade sizes da matriz indica quantos arquivos foram selecionados, de forma que você pode usar um loop for com uma notação de matriz padrão para acessar cada objeto StorageFile. Este exemplo de código instancia e mostra um seletor de arquivo para uma seleção de vários arquivos. // Instantiate a FileOpenPicker object. var openPicker = new Windows.Storage.Pickers.FileOpenPicker(); // Set the FileOpenPicker object's key properties. openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail; openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.picturesLibrary; openPicker.fileTypeFilter.replaceAll([".jpg", ".jpeg", ".png"]); // Display the FileOpenPicker for multiple-file selection. openPicker.pickMultipleFilesAsync().then(function (files) { // If the user selected at least one file ... if (files.size > 0) { for (var i = 0; i < files.size; i++) { // ... process each file - For example, files[i] } } else { // User canceled the operation. } }); Configurando um seletor de pasta Instancie um objeto FolderPicker. Defina o FolderPicker do objeto FolderPicker.viewMode, FolderPicker.suggestedStartLocation e as propriedades de FolderPicker.fileTypeFilter conforme necessário. Chame a função FileOpenPicker.pickSingleFileAsync. Quando a função FolderPicker.pickSingleFolderAsync estiver concluída, o aplicativo possui acesso de leitura/gravação às pastas selecionadas, incluindo subpastas. Este exemplo de código instancia e mostra um seletor de pasta. // Instantiate a FolderPicker object. var folderPicker = new Windows.Storage.Pickers.FolderPicker(); // Set the FileOpenPicker object's key properties. folderPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.desktop; folderPicker.fileTypeFilter.replaceAll([".docx", ".xlsx", ".pptx"]); // Display the FolderPicker for folder selection. folderPicker.pickSingleFolderAsync().then(function (folder) { // If the user selected a folder ... if (folder) { // ... get the folder object. Windows.Storage.AccessCache.StorageApplicationPermissions. futureAccessList.addOrReplace("PickedFolderToken", folder); // Process folder as needed. } else { // User canceled operation. } }); Essa captura de tela mostra os resultados de execução do exemplo e seleção dos dois arquivos (sample1.png e sample2.png). Encontre no exemplo: o exemplo inclui uma página intitulada Seletores de arquivo e pasta, que demonstra as tarefas descritas nesta seção. O código JavaScript e HTML para esse exemplo está nos arquivos FilePickerPage.js e FilePickerPage.html, respectivamente.

 

Trabalhando com arquivos do OneDrive

Guia de início rápido: determinando a disponibilidade de arquivos OneDrive O Windows 8.1 permite que os usuários marquem arquivos do OneDrive como somente online. Quando o usuário se desconecta do OneDrive, esses arquivos não ficam disponíveis. Para ajudar a determinar de forma programática a disponibilidade de um arquivo, há uma nova propriedade chamada StorageFile.isAvailable. Essas etapas mostram como determinar a disponibilidade dos arquivos usando a propriedade StorageFile.isAvailable. Obtenha um objeto StorageFolder para o local que deseja. Por exemplo, você pode fazer isso ao referenciar uma das propriedades KnownFolders estáticas, como KnowFolders.picturesLibrary. Chame a função StorageFolder do objeto StorageFolder.getFilesAsync retornado. O exemplo auxiliar desse tópico chama esse método sem qualquer parâmetro, indicando se todos os arquivos devem ser retornados. Para ver exemplos de chamada StorageFolder.getFilesAsync com uma consulta, consulte Início rápido: acessando arquivos de forma programática. Quando a função StorageFolder.getFilesAsync estiver concluída, você pode usar um loop forEach para iterar em cada arquivo retornado. Este exemplo de código enumera todos os arquivos em Imagens, exibindo cada nome de arquivo, nome de provedor e disponibilidade. // Get a StorageFolder object representing Pictures. var library = Windows.Storage.KnownFolders.picturesLibrary; // Initialize string that will contain the file name, provider name, // and availability for each file. var outString = ""; // Get all files from the StorageFolder object. library.getFilesAsync().then(function (files) { // For each file found ... files.forEach(function (file) { // Retrieve the file's name, provider name, and availability. outString += file.name + " (on " + file.provider.displayName + ") is " + (file.isAvailable ? "available" : "not available") + "\n"; }); }); Essa captura de tela mostra exemplo de resultados da verificação dos arquivos em Imagens para fins de disponibilidade. Encontre no exemplo: o exemplo inclui uma página intitulada "Arquivos do OneDrive", que tem um botão que enumera todos os arquivos na biblioteca de Imagens da máquina local. Cada nome de arquivo é exibido junto com o provedor desse arquivo (por exemplo, Este Computador ou OneDrive) e se o arquivo está ou não disponível atualmente. O código JavaScript e o HTML para esse exemplo estão nos arquivos OneDriveFilesPage.js e OneDriveFilesPage.html, respectivamente.

 

Terminar

	Usando o Kit de Certificação de Aplicativos Windows Recomendado. Executar o Kit de Certificação de Aplicativos para Windows ajuda a garantir que seu aplicativo cumpra os requisitos da Windows Store. Recomendamos que você execute-o sempre que adicionar a funcionalidade principal em seu aplicativo.
	Pronto! Agora que você explorou diferentes recursos de manipulação de arquivos para seu aplicativo, está pronto para criar um aplicativo como o do Exemplo complementar de manipulação de arquivos, do início ao fim.

 

Deseja saber mais?

Guia de início rápido: programação assíncrona em JavaScript

Saiba mais sobre a programação assíncrona em JavaScript.

Guia de início rápido: acessando arquivos de forma programática

Saiba mais sobre enumeração de arquivos.

Guia de início rápido: lendo e gravando um arquivo

Saiba mais sobre leitura e gravação de arquivos.