APIs Storage

Quase todos os aspectos do desenvolvimento de aplicativos envolvem algum elemento de envio ou recebimento de dados. Iniciando com o básico, você deve usar uma estrutura MVC para ajudá-lo a projetar e implementar seu aplicativo para que os dados são completamente separados da visualização do aplicativo sobre esses dados (consulte Arquitetura MVC).

Você também precisa pensar em como os dados são processados quando o app está off-line (consulte Priorização off-line). Este documento apresenta brevemente as opções de armazenamento para enviar, receber e salvar dados localmente. as restante do documento mostra como usar as APIs File System e Sync File System do Chrome (consulte também API fileSystem e API syncFileSystem).

Opções de armazenamento

Os aplicativos em pacotes usam muitos mecanismos diferentes para enviar e receber dados. Para dados externos (recursos, páginas da Web), você precisa conhecer a Política de Segurança de Conteúdo (CSP). Semelhante ao Chrome Extensões, é possível usar XMLHttpRequests de origem cruzada para se comunicar com servidores remotos. Você também podem isolar páginas externas, para que o restante do aplicativo fique seguro. Consulte Incorporar páginas externas ).

Ao salvar dados localmente, você pode usar a API Chrome Storage para salvar pequenas quantidades de strings e IndexedDB para salvar dados estruturados. Com o IndexedDB, você pode manter objetos JavaScript em um armazenamento de objetos e usar os índices da loja para consultar dados. Para saber mais, consulte Simple Todo tutorial de lista). Para todos os outros tipos de dados, como dados binários, use o sistema de arquivos e a sincronização APIs do sistema de arquivos.

As APIs Filesystem e Sync Filesystem do Google Chrome estendem a API HTML5 FileSystem. Com as API Filesystem, os apps podem criar, ler, navegar e gravar em uma seção do sistema do usuário no sistema de arquivos local. Por exemplo, um aplicativo de compartilhamento de fotos pode usar a API Filesystem para ler e gravar qualquer fotos que um usuário seleciona.

Com a API Sync Filesystem do Google Chrome, os aplicativos podem salvar e sincronizar dados no Google Drive de um usuário para que os mesmos dados podem estar disponíveis em clientes diferentes. Por exemplo, um texto com suporte da nuvem Editor pode sincronizar automaticamente novos arquivos de texto com a conta do Google Drive de um usuário. Quando o usuário abre o editor de texto em um novo cliente, o Google Drive envia novos arquivos de texto para essa instância o editor de texto.

Como usar a API Chrome Filesystem

Como adicionar permissão ao sistema de arquivos

Para usar a API File System do Chrome, é necessário adicionar a extensão "fileSystem" permissão ao manifesto, então para que você consiga permissão do usuário para armazenar dados persistentes.

"permissions": [
  "...",
  "fileSystem"
]

Opções do usuário para selecionar arquivos

Os usuários esperam selecionar arquivos da mesma maneira que sempre fazem. No mínimo, eles esperam que uma opção arquivo" e o seletor de arquivos padrão. Caso seu aplicativo use intensamente o envio de arquivos, você também implementar o recurso de arrastar e soltar (veja abaixo e também confira Arrastar e soltar HTML5 nativo).

Como conseguir o caminho de uma fileEntry

Para ver o caminho completo do arquivo que o usuário selecionou, fileEntry, chame getDisplayPath():

function displayPath(fileEntry) {
  chrome.fileSystem.getDisplayPath(fileEntry, function(path) {
    console.log(path)
  });
}

Como implementar o recurso de arrastar e soltar

Se você precisar implementar a seleção de arrastar e soltar, o controlador de arquivos de arrastar e soltar (dnd.js) em a amostra filesystem-access é um bom ponto de partida. O controlador cria uma entrada de arquivo de um DataTransferItem usando o recurso de arrastar e soltar. Neste exemplo, fileEntry é definido como o primeiro item solto.

var dnd = new DnDFileController('body', function(data) {
  var fileEntry = data.items[0].webkitGetAsEntry();
  displayPath(fileEntry);
});

Como ler um arquivo

O código a seguir abre o arquivo (somente leitura) e o lê como texto usando um objeto FileReader. Se o arquivo não existir, será gerado um erro.

var chosenFileEntry = null;

chooseFileButton.addEventListener('click', function(e) {
  chrome.fileSystem.chooseEntry({type: 'openFile'}, function(readOnlyEntry) {

    readOnlyEntry.file(function(file) {
      var reader = new FileReader();

      reader.onerror = errorHandler;
      reader.onloadend = function(e) {
        console.log(e.target.result);
      };

      reader.readAsText(file);
    });
    });
});

Como gravar um arquivo

Os dois casos de uso comuns para gravar um arquivo são "Salvar" e em "Salvar como". O código a seguir cria uma writableEntry do chosenFileEntry somente leitura e grava o arquivo selecionado nele.

 chrome.fileSystem.getWritableEntry(chosenFileEntry, function(writableFileEntry) {
    writableFileEntry.createWriter(function(writer) {
      writer.onerror = errorHandler;
      writer.onwriteend = callback;

    chosenFileEntry.file(function(file) {
      writer.write(file);
    });
  }, errorHandler);
});

O código a seguir cria um novo arquivo com a opção "Save as" e grava o novo blob no usando o método writer.write().

chrome.fileSystem.chooseEntry({type: 'saveFile'}, function(writableFileEntry) {
    writableFileEntry.createWriter(function(writer) {
      writer.onerror = errorHandler;
      writer.onwriteend = function(e) {
        console.log('write complete');
      };
      writer.write(new Blob(['1234567890'], {type: 'text/plain'}));
    }, errorHandler);
});

Como usar a API Chrome Sync Filesystem

Com o armazenamento de arquivos sincronizáveis, os objetos de dados retornados podem ser operados da mesma maneira que os sistemas de arquivos off-line na API FileSystem, mas com a sincronização adicionada (e automática) desses sistemas para o Google Drive.

Adicionando permissão do sistema de arquivos de sincronização

Para usar a API Sync Filesystem do Google Chrome, é necessário adicionar a pasta "syncFileSystem" para o para que você possa obter permissão do usuário para armazenar e sincronizar dados persistentes.

"permissions": [
  "...",
  "syncFileSystem"
]

Iniciando o armazenamento de arquivos sincronizáveis

Para iniciar o armazenamento de arquivos sincronizáveis no app, basta chamar syncFileSystem.requestFileSystem. Esse método retorna um sistema de arquivos sincronizável apoiado pelo Google Drive, por exemplo:

chrome.syncFileSystem.requestFileSystem(function (fs) {
   // FileSystem API should just work on the returned 'fs'.
   fs.root.getFile('test.txt', {create:true}, getEntryCallback, errorCallback);
});

Sobre o status de sincronização de arquivos

Use syncFileSystem.getFileStatus para ver o status de sincronização de um arquivo atual:

chrome.syncFileSystem.getFileStatus(entry, function(status) {...});

Os valores de status da sincronização de arquivos podem ser um dos seguintes: 'synced', 'pending' ou 'conflicting'. "Sincronizado" significa que o arquivo está totalmente sincronizado. que não há alterações locais pendentes sincronizados com o Google Drive. No entanto, pode haver alterações pendentes no Google Drive que que ainda não foram buscados.

"Pendente" significa que o arquivo tem alterações pendentes ainda não sincronizadas com o Google Drive. Se o app for em execução on-line, as alterações locais são (quase) imediatamente sincronizadas com o Google Drive e a O evento syncFileSystem.onFileStatusChanged é acionado com o status 'synced' (veja abaixo mais detalhes).

O syncFileSystem.onFileStatusChanged é acionado quando o status de um arquivo é alterado para 'conflicting' "Conflito" significa que há alterações conflitantes no armazenamento local e Google Drive Um arquivo só poderá ter esse estado se a política de resolução de conflitos estiver definida como 'manual': A política padrão é 'last_write_win', e os conflitos são resolvidos automaticamente por política mais simples de última gravação. A política de resolução de conflitos do sistema pode ser alterada syncFileSystem.setConflictResolutionPolicy.

Se a política de resolução de conflitos for definida como 'manual' e um arquivo resultar no estado 'conflicting', o app ainda poderá ler e gravar o arquivo como um arquivo off-line local, mas as mudanças não serão sincronizadas. e o arquivo será mantido separado das alterações remotas feitas em outros clientes até que o conflito seja resolvido. resolvido. A maneira mais fácil de resolver um conflito é excluir ou renomear a versão local de um arquivo. Isso força a versão remota a ser sincronizada, o estado conflitante é resolvido e a O evento onFileStatusChanged é disparado com o status 'synced'.

Detectar mudanças no status sincronizado

O evento syncFileSystem.onFileStatusChanged é acionado quando o status de sincronização de um arquivo é alterado. Por exemplo, suponha que um arquivo tenha alterações pendentes e esteja no marcador "pendente" estado. O aplicativo pode ter sido em estado off-line para que a alteração esteja prestes a ser sincronizada. Quando o serviço de sincronização detecta a alteração local pendente e fizer o upload da alteração para o Google Drive, o serviço acionará o Evento onFileStatusChanged com os seguintes valores: { fileEntry:a fileEntry for the file, status: 'synced', action: 'updated', direction: 'local_to_remote' }.

Da mesma forma, independentemente das atividades locais, o serviço de sincronização pode detectar alterações remotas feitas por outro cliente e faz o download das alterações do Google Drive para o armazenamento local. Se o controle remoto alteração foi adicionar um novo arquivo, um evento com os seguintes valores será disparado: { fileEntry: a fileEntry for the file, status: 'synced', action: 'added', direction: 'remote_to_local' }:

Se o lado local e o remoto tiverem alterações conflitantes para o mesmo arquivo e se o conflito de resolução for definida como 'manual', o status do arquivo será alterado para o estado conflicting, será desconectados do serviço de sincronização e não serão sincronizados até que o conflito seja resolvido. Neste caso um evento com os seguintes valores seja disparado: { fileEntry: a fileEntry for the file, status: 'conflicting', action: null, direction: null }:

Você pode adicionar um listener a esse evento que responda a qualquer alteração no status. Por exemplo, o O aplicativo Player de música do Chrome ouve as novas músicas sincronizadas do Google Drive, mas ainda não importados para o armazenamento local do usuário em um cliente específico. Todas as músicas encontradas serão sincronizadas cliente:

chrome.syncFileSystem.onFileStatusChanged.addListener(function(fileInfo) {
  if (fileInfo.status === 'synced') {
    if (fileInfo.direction === 'remote_to_local') {
      if (fileInfo.action === 'added') {
        db.add(fileInfo.fileEntry);
      } else if (fileInfo.action === 'deleted') {
        db.remove(fileInfo.fileEntry);
      }
    }
  }
});

Verificar o uso da API

Para verificar a quantidade de dados em uso pela API, consulte o diretório local no sandbox do app ou o bytes de uso retornados por syncFileSystem.getUsageAndQuota:

chrome.syncFileSystem.getUsageAndQuota(fileSystem, function (storageInfo) {
   updateUsageInfo(storageInfo.usageBytes);
   updateQuotaInfo(storageInfo.quotaBytes);
});

Também é possível verificar o armazenamento do serviço de back-end de sincronização do usuário (no Google Drive). Os arquivos sincronizados são salva em uma pasta oculta do Google Drive, Chrome Syncable FileSystem. A pasta não vai aparecer em seu "Meu Drive" lista, mas pode ser acessado pesquisando o nome da pasta na caixa de pesquisa. (Observe que o layout de pasta remota não garante a compatibilidade com versões anteriores entre as versões.