Gerenciando o armazenamento off-line HTML5

O HTML5 introduziu muitas APIs de armazenamento que permitem armazenar uma grande quantidade de dados localmente nos navegadores dos usuários. Mas, por padrão, a quantidade de espaço alocada para cada app é restrita a alguns megabytes. O Google Chrome permite solicitar uma cota de armazenamento maior, além do limite anterior de apenas 5 MB.

Este documento apresenta os conceitos básicos relacionados aos tipos de armazenamento usados no Chrome e descreve a API experimental de gerenciamento de cotas, que permite gerenciar sua cota de armazenamento. O documento pressupõe que você já conhece os conceitos gerais de armazenamento do lado do cliente e sabe como usar APIs off-line.

Conteúdo

1. Tipos de armazenamento
   1. Temporário
   2. Persistente
   3. Sem limites
   4. Comparação entre tipos de armazenamento
2. Como gerenciar sua cota
   1. Consultar o uso e a disponibilidade do armazenamento
   2. Pedir mais armazenamento
   3. Redefinir cota para testes
3. Referência da API
   1. Constantes
   2. Visão geral do método
   3. Métodos
4. Desenvolvimento futuro

Tipos de armazenamento

No Google Chrome, é possível solicitar três tipos de armazenamento:

• Temporário
• Persistente
• Sem limites

Esses tipos de armazenamento são descritos em mais detalhes nas seções a seguir e comparados entre si na tabela abaixo.

Armazenamento temporário

O armazenamento temporário é um armazenamento temporário disponível para qualquer app da Web. O Chrome fornece armazenamento temporário ao seu app automaticamente. Assim, você não precisa solicitar a alocação.

Como compartilhar o pool

O armazenamento temporário é compartilhado entre todos os apps da Web em execução no navegador. O pool compartilhado pode ser até 1/3 do espaço disponível em disco. O armazenamento já usado por apps é incluído no cálculo do pool compartilhado. Ou seja, o cálculo é baseado em (available storage space + storage being used by apps) * .333.

Cada app pode ter até 20% do pool compartilhado. Por exemplo, se o espaço total disponível em disco é de 60 GB, o pool compartilhado é de 20 GB, e o app pode ter até 4 GB. Isso é calculado a partir de 20% (até 4 GB) de 1/3 (até 20 GB) do espaço disponível em disco (60 GB).

Pedir mais espaço

Embora você possa consultar a quantidade de espaço de armazenamento disponível para o app e a quantidade de dados já armazenados no app, não é possível solicitar mais espaço de armazenamento temporário. Se um app exceder a cota alocada, será gerado um erro.

Falta de armazenamento

Quando a cota de armazenamento de todo o pool é excedida, todos os dados armazenados no host usado menos recentemente são excluídos. No entanto, o navegador não eliminará os dados do LocalStorage e do SessionStorage. Para dados armazenados em outras APIs off-line, o navegador exclui os dados por completo, e não em parte, para que os dados do app não sejam corrompidos de maneiras inesperadas.

Como cada app é limitado a no máximo 20% do pool de armazenamento, a exclusão provavelmente só vai ocorrer se o usuário estiver executando mais de cinco apps off-line, cada um usando o armazenamento máximo.

No entanto, o espaço de armazenamento disponível pode diminuir à medida que os usuários adicionam mais arquivos aos discos rígidos. Quando o espaço em disco disponível fica reduzido (lembre-se de que o pool compartilhado recebe apenas metade do espaço atual disponível em disco), o navegador exclui todos os dados do host usado menos recentemente.

Armazenamento persistente

O armazenamento permanente é aquele que permanece no navegador, a menos que o usuário o exclua. Ela está disponível apenas para apps que usam a API File System, mas no futuro será disponibilizada para outras APIs off-line, como a IndexedDB e o Application Cache.

Um aplicativo pode ter uma cota maior para armazenamento permanente do que o armazenamento temporário, mas você precisa solicitar armazenamento usando a API Cota Management e o usuário precisa conceder permissão para usar mais espaço. O Chrome apresenta uma barra de informações que solicita que o usuário conceda mais espaço de armazenamento local ao app.

Armazenamento ilimitado

O armazenamento ilimitado é semelhante ao armazenamento permanente, mas está disponível apenas para apps e extensões do Chrome (arquivos .crx). O tamanho do armazenamento ilimitado é limitado apenas pela disponibilidade de espaço no disco rígido do usuário. Você pode solicitar a permissão unlimitedStorage no arquivo de manifesto para um app ou extensão. Na instalação, o usuário é informado sobre as permissões exigidas pelo app ou pela extensão. Ao prosseguir com a instalação, o usuário concede permissão implícita para todas as páginas com URLs listados no arquivo manifest.json.

Para saber mais, consulte os respectivos guias do desenvolvedor para aplicativos e extensões.

Comparação entre tipos de armazenamento

A tabela a seguir descreve as diferenças entre os três tipos de armazenamento.

Como gerenciar sua cota

Com a API Cota Management, que foi introduzida no Chrome 13, você pode fazer o seguinte:

• Consultar o uso e a disponibilidade do armazenamento
• Pedir mais armazenamento
• Redefinir cota para testes

A API é implementada com o objeto global window.webkitStorageInfo.

Para ver a documentação de referência, consulte a próxima seção.

Como consultar o uso e a disponibilidade do armazenamento

Para consultar o tamanho do armazenamento que está sendo usado e o espaço disponível restante para o host, chame queryUsageAndQuota() com o seguinte:

• Tipo de armazenamento que você quer verificar
• Chamada de retorno concluída

O uso relatado pela API pode não corresponder ao tamanho real dos dados do usuário, já que cada armazenamento pode precisar de bytes extras para armazenar os metadados. Além disso, as atualizações de status podem demorar, fazendo com que a API não reflita o status de armazenamento mais recente.

O snippet de código a seguir mostra como perguntar sobre o espaço de armazenamento:

// Request storage usage and capacity left
// Choose either Temporary or Persistent
navigator.webkitTemporaryStorage.queryUsageAndQuota (
    function(usedBytes, grantedBytes) {
        console.log('we are using ', usedBytes, ' of ', grantedBytes, 'bytes');
    },
    function(e) { console.log('Error', e);  }
);

Se você quiser solicitar o status do armazenamento permanente, basta substituir webkitStorageInfo.TEMPORARY por webkitStorageInfo.PERSISTENT. A enumeração também está no objeto window (namespace global), então você também pode usar window.PERSISTENT e window.TEMPORARY.

Pedir mais armazenamento

Não é necessário solicitar mais armazenamento temporário porque a alocação é automática e você não pode ultrapassar o limite máximo, conforme descrito na tabela.

A cota padrão para armazenamento permanente da API File System é 0. Portanto, é necessário solicitar explicitamente o armazenamento para seu aplicativo. Chame requestQuota() com o seguinte:

• Tipo de armazenamento
• Tamanho
• Chamada de retorno concluída

Dependendo do que você pedir, acontece o seguinte:

• Se você solicitar uma cota maior, o navegador apresentará uma barra de informações ao usuário e solicitará que ele conceda ou negue a permissão para aumentar a cota. Em alguns casos, a solicitação pode ser rejeitada silenciosamente, e a cota atual ou uma cota menor será retornada.
• Se a quantidade de cota solicitada for menor do que a alocação atual do aplicativo, nenhuma solicitação será exibida.
• Se você pedir mais armazenamento do que o permitido, um erro (QUOTA_EXCEEDED_ERR) vai aparecer.
• Se você chamar requestQuota() novamente depois que o usuário já tiver concedido permissão, nada acontecerá. Por isso, não se preocupe em chamar o método novamente.

Veja a seguir como solicitar mais espaço de armazenamento:

// Request Quota (only for File System API)
var requestedBytes = 1024*1024*10; // 10MB

navigator.webkitPersistentStorage.requestQuota (
    requestedBytes, function(grantedBytes) {
        window.requestFileSystem(PERSISTENT, grantedBytes, onInitFs, errorHandler);

    }, function(e) { console.log('Error', e); }
);
});

Como redefinir a cota para testes

Ao testar o armazenamento no app, limpe os dados armazenados para testar novamente o gerenciamento de cotas. Para isso, siga estas etapas:

1. Digite chrome://settings/cookies na omnibox (barra de endereço).
2. Procure seu app.
3. Selecione seu app.
4. Clique no X no lado direito da seleção destacada.

Referência da API

Esta seção documenta os métodos da API de gerenciamento de cotas.

Constantes

A seguir estão as constantes webkitStorageInfo, que indicam o tipo de armazenamento.

Visão geral dos métodos

Métodos

queryUsageAndQuota

Verifique o tamanho do armazenamento que está sendo usado e o espaço disponível restante para o host.

 // you could also use it from webkitPersistentStorage
navigator.webkitTemporaryStorage.queryUsageAndQuota(
      successCallback,
      errorCallback);

• successCallback: callback opcional com dois parâmetros:

  • O número atual de bytes que o app está usando.
  • O número de bytes restantes na cota.

• errorCallback: callback de erro opcional.

requestQuota

Solicite mais armazenamento. O navegador apresenta uma barra de informações para solicitar que o usuário conceda ou negue ao app a permissão para ter mais armazenamento.

 // you could also use it from webkitTemporaryStorage
navigator.webkitPersistentStorage.requestQuota (
      newQuotaInBytes,
      quotaCallback,
      errorCallback);

Parâmetros

• newQuotaInBytes: a quantidade de bytes que você quer na sua cota de armazenamento.
• successCallback: callback opcional que transmite a quantidade de bytes concedidos.
• errorCallback: callback de erro opcional.

Desenvolvimento futuro

O plano é colocar todas as APIs de armazenamento off-line HTML5, incluindo IndexedDB, Application Cache, File System e outras APIs que possam ser especificadas, na API quota Management. Com ele, é possível gerenciar toda a alocação de armazenamento.