Guia de início rápido: lendo e gravando 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]

Leia e grave um arquivo usando um objeto StorageFile.

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
Saiba como obter o arquivo do qual você quer ler ou no qual você quer gravar

Você pode aprender a obter um arquivo chamando um seletor de arquivos em Início Rápido: acessando arquivos com seletores de arquivos.

O arquivo usado nos exemplos

Todo o código nestes exemplos é retirado do Exemplo de acesso a arquivos e depende da mesma variável global sampleFile do exemplo. Essa variável representa o arquivo (sample.dat) que a amostra grava e lê nos exemplos.

O Exemplo de acesso de arquivos cria o arquivo sample.dat e armazena o objeto storageFile que é retornado da seguinte forma:

Windows.Storage.ApplicationData.current.localFolder.createFileAsync("sample.dat",
    Windows.Storage.CreationCollisionOption.replaceExisting).then(function (file) {
        sampleFile = file;
    });

Observação Para que você possa criar arquivos em bibliotecas, é necessário declarar as funcionalidades no manifesto do seu aplicativo. Para saber mais sobre o acesso a arquivo e funcionalidades, veja Acesso a arquivo e permissões e Acesso a recursos do usuário usando o Tempo de Execução do Windows.

Gravando em um arquivo

Estas etapas mostram como gravar em um arquivo se você tem um arquivo gravável e um storageFile que o representa.

Gravando texto em um arquivo

Grave texto no seu arquivo chamando os métodos writeTextAsync da classe fileIO.

O Exemplo de acesso a arquivos mostra como chamar writeTextAsync(file, contents) para gravar um texto arbitrário no seu sampleFile da seguinte forma:

Windows.Storage.FileIO.writeTextAsync(sampleFile, "Swift as a shadow").then(function () {
    // Add code to do something after the text is written to the file
});

Apesar dos métodos writeTextAsync não possuírem um valor de retorno, você pode usar then ou done para declarar uma função e realizar tarefas adicionais depois que o texto é gravado em um arquivo, conforme mostrado pelo exemplo.

Gravando bytes em um arquivo usando um buffer

Obtenha um buffer dos bytes que você deseja gravar no seu arquivo.

Por exemplo, a Exemplo de acesso a arquivos chama convertStringToBinary para obter um buffer de bytes baseado em uma cadeia de caracteres arbitrária da seguinte forma:
```
var buffer = Windows.Security.Cryptography.CryptographicBuffer.convertStringToBinary(
    'What fools these mortals be', Windows.Security.Cryptography.BinaryStringEncoding['']
);
```
Grave os bytes do seu buffer no seu arquivo chamando o método writeBufferAsync da classe fileIO.

O Exemplo de acesso a arquivos mostra como usar writeBufferAsync para gravar bytes de um buffer em seu sampleFile da seguinte forma:
```
Windows.Storage.FileIO.writeBufferAsync(sampleFile, buffer).then(function () {
    // Add code to do something after the text is written to the file
});
```
Apesar de writeBufferAsync não possuir um valor de retorno, você pode usar then ou done para declarar uma função e realizar tarefas adicionais depois que o texto é gravado em um arquivo, conforme mostrado pelo exemplo.

Gravando texto em um arquivo usando um fluxo transacionado

Abra um fluxo para o seu arquivo chamando o método storageFile.openTransactedWriteAsync. Ele retorna um fluxo de conteúdo do arquivo quando a operação de abertura é concluída.

O Exemplo de acesso de arquivo mostra como abrir um fluxo para um arquivo (sampleFile) chamando o método storageFile.openTransactedWriteAsync da seguinte forma:
```
sampleFile.openTransactedWriteAsync().then(writeToStream);
```
Declare uma função (como writeToStream) para capturar o transaction (tipo StorageStreamTransaction) para que você possa gravar no arquivo após a conclusão do método, da seguinte forma:
```
function writeToStream(transaction) {
    // Add code to use the stream to write to your file
}
```
Use estas etapas para adicionar código à sua função writeToStream que gravará texto no seu arquivo após a conclusão do método storageFile.openAsync.
1. Use o transaction para gravar texto no fluxo criando um novo objeto dataWriter e chamando o método dataWriter.writeString.
  
  A Exemplo de acesso a arquivos mostra como gravar texto no fluxo da seguinte forma:
```
var dataWriter = new Windows.Storage.Streams.DataWriter(transaction.stream);
dataWriter.writeString("Swift as a shadow");
```
2. Salve o texto no arquivo e feche o fluxo chamando os métodos .dataWriter.storeAsync e transaction.commitAsync.
  
  A Exemplo de acesso a arquivos mostra como salvar o texto no seu arquivo e fechar o fluxo da seguinte forma:
```
dataWriter.storeAsync().then(function () {
    transaction.commitAsync().done(function () {
        // Text in stream has been saved to the file
        transaction.close();
    });
});
```

Você pode baixar a Exemplo de acesso de arquivos para ver esses exemplos de código contextualizados dentro de funções.

Lendo um arquivo

Estas etapas mostram como ler um arquivo se você tem um arquivo gravável e um storageFile que o representa.

Lendo texto de um arquivo

Leia texto do seu arquivo chamando os métodos readTextAsync da classe fileIO.

O Exemplo de acesso a arquivos lhe mostra como ler texto de um arquivo chamando readTextAsync(file) para ler do seu sampleFile da seguinte forma:

Windows.Storage.FileIO.readTextAsync(sampleFile).then(function (contents) {
    // Add code to process the text read from the file
});

Você pode usar then ou done para declarar uma função para capturar e processar o texto que foi lido do arquivo. Após a conclusão do método readTextAsync, o texto é passado para essa função como um objeto String (contents na amostra).

Lendo bytes de um arquivo usando um buffer

Leia os bytes do seu arquivo em um buffer chamando o método readBufferAsync da classe fileIO.

O Exemplo de acesso a arquivos mostra como ler bytes para um buffer de um arquivo chamando readBufferAsync da seguinte forma:

Windows.Storage.FileIO.readBufferAsync(sampleFile).then(function (buffer) {
    // Add code to process the text read from the file
});

Você pode usar then ou done para declarar uma função para capturar e processar os dados do buffer (tipo IBuffer) após a conclusão do método readBufferAsync.

Por exemplo, a Amostra de acesso a arquivos captura o buffer e usa um objeto dataReader para ler o tamanho do buffer da seguinte forma:

Windows.Storage.FileIO.readBufferAsync(sampleFile).then(function (buffer) {
    var dataReader = Windows.Storage.Streams.DataReader.fromBuffer(buffer);
    var output = dataReader.readString(buffer.length);
});

Evidentemente, ler o tamanho do buffer dessa maneira não é especialmente útil, mas você está livre para usar a criatividade para processar o buffer. Talvez você queira olhar os métodos disponibilizados pela classe dataReader para ter uma ideia do que você pode fazer.

Lendo texto de um arquivo usando um fluxo

Abra um fluxo do seu arquivo chamando o método storageFile.openAsync. Ele retorna um fluxo de conteúdo do arquivo quando a operação de abertura é concluída.

O Exemplo de acesso de arquivo mostra como abrir um fluxo para um arquivo (sampleFile) chamando o método storageFile.openAsync da seguinte forma:
```
sampleFile.openAsync(Windows.Storage.FileAccessMode.readWrite).then(readFromStream);
```
Certifique-se de declarar uma função (como readFromStream) para capturar o fluxo (tipo IRandomAccessStream) para que você possa ler o seu conteúdo após a conclusão do método da seguinte forma:
```
function readFromStream(readStream) {
    // Add code to use the stream to read text from your file
}
```
Use estas etapas para adicionar código à sua função readFromStream que lerá texto do seu arquivo após a conclusão do método storageFile.openAsync.
1. Obtenha um objeto dataReader para ler o readStream.
  
  O Exemplo de acesso de arquivo mostra como obter um dataReader a seguinte forma:
```
var dataReader = new Windows.Storage.Streams.DataReader(readStream);
```
2. Leia o texto chamando os métodos dataReader.loadAsync e dataReader.readString.
  
  O Exemplo de acesso de arquivo mostra como ler texto da seguinte forma:
```
dataReader.loadAsync(readStream.size).done(function (numBytesLoaded) {
    var fileContent = dataReader.readString(numBytesLoaded);
    // Process text read from the file
    dataReader.close();
});
```