Como salvar arquivos usando 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]

Use o fileSavePicker para permitir que os usuários especifiquem o nome e o local onde desejam salvar o conteúdo do seu aplicativo.

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

Instruções

Etapa 1: Criar e personalizar o seletor de arquivos para exibir os locais de salvamento

Use o fileSavePicker para que o usuário possa especificar o nome, o tipo de arquivo e o local de salvamento de um arquivo. Você pode personalizar o seletor de arquivos configurando as propriedades no fileSavePicker criado.

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

// Create the picker object and set options
var savePicker = new Windows.Storage.Pickers.FileSavePicker();
savePicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.documentsLibrary;
// Dropdown of file types the user can save the file as
savePicker.fileTypeChoices.insert("Plain Text", [".txt"]);
// Default file name if the user does not type one in or select a file to replace
savePicker.suggestedFileName = "New Document";

Você deve definir propriedades fileSavePicker que sejam relevantes para seus usuários e seu aplicativo. Para obter diretrizes para ajudá-lo a decidir como personalizar o seletor de arquivos, veja Diretrizes e lista de verificação para os seletores de arquivos.

O Exemplo do seletor de arquivos personaliza o seletor de arquivos configurando três propriedades do fileSavePicker: suggestedStartLocation, fileTypeChoices e suggestedFileName.

Observação Os objetos do fileSavePicker usam pickerViewMode.list para exibir dados.

JJ150595.wedge(pt-br,WIN.10).gif Personalizando um fileSavePicker, em detalhes

Como nosso usuário está salvando um documento ou arquivo de texto, a amostra define savePicker.suggestedStartLocation como a pasta local do aplicativo usando LocalFolder.
```
savePicker.suggestedStartLocation = Windows.Storage.ApplicationData.localFolder;
```
Você deve definir 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 a pasta local do aplicativo. Este é apenas um local inicial. Os usuários podem navegar para outros locais enquanto usam o seletor de arquivos.
Como desejamos que nosso aplicativo abra o arquivo depois dele ser salvo, a amostra usa savePicker.fileTypeChoices.insert para especificar os tipos de arquivos que a amostra suporta (documentos do Microsoft Word e arquivos de texto).
```
savePicker.fileTypeChoices.insert("Plain Text", [".txt"]);
```
Certifique-se de que todos os tipos de arquivos sejam suportados por seu aplicativo.

Os usuários poderão salvar seus arquivos como qualquer tipo de arquivo que você especificar na lista. Eles também poderão alterar o tipo de arquivo selecionando um tipo de arquivo diferente (que você especificou) no controle suspenso na parte inferior direita do seletor de arquivos. A primeira escolha de tipo de arquivo na lista será selecionada por padrão. Para alterar qual tipo de arquivo é selecionado por padrão, defina a propriedade savePicker.defaultFileExtension.

Observação O seletor de arquivo também utiliza o tipo de arquivo atualmente selecionado para filtrar quais arquivos são exibidos, de forma que os únicos tipos de arquivos que correspondem aos tipos de arquivos selecionados são exibidos para o usuário.
Como desejamos salvar um tipo para o usuário, a amostra define umsavePicker.suggestedFileName para salvar o arquivo.
```
savePicker.suggestedFileName = "New Document";
```
Tente deixar as sugestões de nome de arquivo o mais relevantes possíveis para o arquivo que seu usuário está salvando. Por exemplo, como no Word, você pode sugerir o nome de arquivo existente se houver um, ou a primeira linha de um documento se o usuário estiver salvando um arquivo que ainda não possui nome.

Etapa 2: Mostrar o fileSavePicker para salvar um arquivo

Após criar e personalizar o seletor de arquivos, permita que o usuário salvar o arquivo chamando savePicker.pickSaveFileAsync.

Depois que o usuário especifica nome, tipo e local do arquivo e confirma que os arquivos devem ser salvos, pickSaveFileAsync retorna um objeto storageFile, que representa o arquivo salvo. Você pode capturar e processar esse arquivo usando then ou done.

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

savePicker.pickSaveFileAsync().then(function (file) {
    if (file) {
        // Prevent updates to the remote version of the file until we finish making changes and call CompleteUpdatesAsync.
        Windows.Storage.CachedFileManager.deferUpdates(file);
        // write to file
        Windows.Storage.FileIO.writeTextAsync(file, file.name).done(function () {
            // Let Windows know that we're finished changing the file so the other app can update the remote version of the file.
            // Completing updates may require Windows to ask for user input.
            Windows.Storage.CachedFileManager.completeUpdatesAsync(file).done(function (updateStatus) {
                if (updateStatus === Windows.Storage.Provider.FileUpdateStatus.complete) {
                    WinJS.log && WinJS.log("File " + file.name + " was saved.", "sample", "status");
                } else {
                    WinJS.log && WinJS.log("File " + file.name + " couldn't be saved.", "sample", "status");
                }
            });
        });
    } else {
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});

Depois que o arquivo é salvo, o aplicativo lê e grava o acesso a esse arquivo. O exemplo captura o arquivo salvo no parâmetro file e verifica se o arquivo é válido, mas o exemplo não processa realmente o arquivo. Você pode saber mais sobre como gravar e ler o arquivo resultante em Guia de início rápido: Lendo e gravando um arquivo.

Dica Sempre verifique o arquivo salvo (file no exemplo) para ter certeza de sua validade antes de executar qualquer outro processamento. Depois disso, você poderá salvar o conteúdo no arquivo, conforme o adequado ao seu aplicativo, e fornecer o comportamento apropriado, se o arquivo selecionado não for válido.

Comentários

Se usar código similar ao que mostramos aqui, o seu aplicativo deverá exibir o seletor de arquivos para os usuários e os deixará especificar nome, tipo e local do arquivo a ser salvo. Saiba mais sobre como gravar e ler o arquivo resultante em Guia de início rápido: Lendo e gravando um arquivo

Se quiser acrescentar o recurso "salvar como" ao aplicativo, adicione um controle para que a interface do usuário chame fileSavePicker. Para saber como adicionar controles, consulte Adicionando controles e conteúdo.

Se quiser que o aplicativo forneça um local de salvamento aos usuários por meio do seletor de arquivos, consulte Guia de início rápido: Integrando contratos de seletor de arquivos.