chrome.storage

Descrição

Use a API chrome.storage para armazenar, extrair e rastrear mudanças nos dados do usuário.

Permissões

storage

Para usar a API Storage, declare a permissão "storage" no manifesto da extensão. Exemplo:

{
  "name": "My extension",
  ...
  "permissions": [
    "storage"
  ],
  ...
}

Conceitos e uso

A API Storage fornece uma maneira específica da extensão de manter os dados e o estado do usuário. Ele é semelhante às APIs de armazenamento da plataforma da Web (IndexedDB e Storage), mas foi projetado para atender às necessidades de armazenamento das extensões. Estes são alguns dos principais recursos:

  • Todos os contextos de extensão, incluindo o service worker de extensão e scripts de conteúdo, têm acesso à API Storage.
  • Os valores serializáveis JSON são armazenados como propriedades de um objeto.
  • A API Storage é assíncrona com operações de leitura e gravação em massa.
  • Mesmo que o usuário limpe o cache e o histórico de navegação, os dados vão persistir.
  • As configurações armazenadas são mantidas mesmo quando você usa o modo de navegação anônima.
  • Inclui uma área de armazenamento gerenciado exclusiva e somente leitura para políticas empresariais.

Extensões podem usar APIs de armazenamento da Web?

Embora as extensões possam usar a interface Storage (acessível de window.localStorage) em alguns contextos (pop-ups e outras páginas HTML), não recomendamos esse uso pelos seguintes motivos:

  • Os service workers de extensão não podem usar a API Web Storage.
  • Os scripts de conteúdo compartilham o armazenamento com a página do host.
  • Os dados salvos usando a API Web Storage são perdidos quando o usuário limpa o histórico de navegação.

Para mover dados de APIs de armazenamento da Web para APIs de armazenamento de extensões de um service worker:

  1. Prepare uma página html de documento fora da tela e um arquivo de script. O arquivo de script precisa conter uma rotina de conversão e um gerenciador onMessage.
  2. No service worker de extensão, verifique seus dados em chrome.storage.
  3. Se os dados não forem encontrados, chame createDocument().
  4. Depois que a promessa retornada for resolvida, chame sendMessage() para iniciar a rotina de conversão.
  5. No gerenciador onMessage do documento fora da tela, chame a rotina de conversão.

Há também algumas nuances na forma como as APIs de armazenamento da Web funcionam em extensões. Saiba mais no artigo Armazenamento e cookies.

Áreas de armazenamento

A API Storage é dividida nas seguintes áreas de armazenamento:

storage.local
Os dados são armazenados localmente e apagados quando a extensão é removida. O limite de armazenamento é de 10 MB (5 MB no Chrome 113 e anterior), mas pode ser aumentado solicitando a permissão "unlimitedStorage". Recomendamos o uso de storage.local para armazenar grandes quantidades de dados.
storage.managed
O armazenamento gerenciado é um armazenamento somente leitura para extensões instaladas em políticas e gerenciado por administradores do sistema usando um esquema definido pelo desenvolvedor e políticas corporativas. As políticas são semelhantes às opções, mas são configuradas por um administrador do sistema, e não pelo usuário. Isso permite que a extensão seja pré-configurada para todos os usuários de uma organização. Para mais informações sobre políticas, consulte Documentação para administradores. Para saber mais sobre a área de armazenamento do managed, consulte Manifesto para áreas de armazenamento.
storage.session
Mantém os dados na memória durante uma sessão do navegador. Por padrão, ele não é exposto a scripts de conteúdo, mas esse comportamento pode ser alterado configurando-se chrome.storage.session.setAccessLevel(). O limite de armazenamento é de 10 MB (1 MB no Chrome 111 e versões anteriores). A interface storage.session é uma das várias recomendadas para service workers.
storage.sync
Se a sincronização estiver ativada, os dados serão sincronizados com o navegador Chrome em que o usuário tiver feito login. Se desativada, ela se comporta como storage.local. O Chrome armazena os dados localmente quando o navegador está off-line e retoma a sincronização quando fica on-line novamente. O limite de cota é de aproximadamente 100 KB, com 8 KB por item. Recomendamos o uso de storage.sync para preservar as configurações do usuário nos navegadores sincronizados. Se você estiver trabalhando com dados sensíveis do usuário, use storage.session.

Limites de armazenamento e limitação

A API Storage tem as seguintes limitações de uso:

  • O armazenamento de dados geralmente tem custos de desempenho, e a API inclui cotas de armazenamento. Recomendamos que você tenha cuidado com os dados que armazena para não perder a capacidade de armazená-los.
  • O armazenamento pode levar algum tempo para ser concluído. Organize seu código para considerar esse tempo.

Veja mais detalhes sobre as limitações da área de armazenamento e o que acontece quando elas são excedidas nas informações de cota do sync, local e session.

Casos de uso

As seções a seguir demonstram casos de uso comuns da API Storage.

Resposta síncrona a atualizações de armazenamento

Para rastrear as alterações feitas no armazenamento, adicione um listener ao evento onChanged. Quando algo muda no armazenamento, o evento é disparado. O exemplo de código detecta essas alterações:

background.js:

chrome.storage.onChanged.addListener((changes, namespace) => {
  for (let [key, { oldValue, newValue }] of Object.entries(changes)) {
    console.log(
      `Storage key "${key}" in namespace "${namespace}" changed.`,
      `Old value was "${oldValue}", new value is "${newValue}".`
    );
  }
});

Podemos levar essa ideia ainda mais longe. Neste exemplo, temos uma página de opções que permite ao usuário ativar ou desativar um "modo de depuração" (implementação não mostrada aqui). A página de opções salva imediatamente as novas configurações em storage.sync, e o service worker usa storage.onChanged para aplicar a configuração o mais rápido possível.

options.html:

<!-- type="module" allows you to use top level await -->
<script defer src="options.js" type="module"></script>
<form id="optionsForm">
  <label for="debug">
    <input type="checkbox" name="debug" id="debug">
    Enable debug mode
  </label>
</form>

options.js:

// In-page cache of the user's options
const options = {};
const optionsForm = document.getElementById("optionsForm");

// Immediately persist options changes
optionsForm.debug.addEventListener("change", (event) => {
  options.debug = event.target.checked;
  chrome.storage.sync.set({ options });
});

// Initialize the form with the user's option settings
const data = await chrome.storage.sync.get("options");
Object.assign(options, data.options);
optionsForm.debug.checked = Boolean(options.debug);

background.js:

function setDebugMode() { /* ... */ }

// Watch for changes to the user's options & apply them
chrome.storage.onChanged.addListener((changes, area) => {
  if (area === 'sync' && changes.options?.newValue) {
    const debugMode = Boolean(changes.options.newValue.debug);
    console.log('enable debug mode?', debugMode);
    setDebugMode(debugMode);
  }
});

Pré-carregamento assíncrono do armazenamento

Como os service workers não são executados o tempo todo, as extensões do Manifest V3 às vezes precisam carregar dados do armazenamento de forma assíncrona antes de executarem os manipuladores de eventos. Para fazer isso, o snippet a seguir usa um manipulador de eventos action.onClicked assíncrono que aguarda o preenchimento do global storageCache antes de executar a lógica.

background.js:

// Where we will expose all the data we retrieve from storage.sync.
const storageCache = { count: 0 };
// Asynchronously retrieve data from storage.sync, then cache it.
const initStorageCache = chrome.storage.sync.get().then((items) => {
  // Copy the data retrieved from storage into storageCache.
  Object.assign(storageCache, items);
});

chrome.action.onClicked.addListener(async (tab) => {
  try {
    await initStorageCache;
  } catch (e) {
    // Handle error that occurred during storage initialization.
  }

  // Normal action handler logic.
  storageCache.count++;
  storageCache.lastTabId = tab.id;
  chrome.storage.sync.set(storageCache);
});

Exemplos

Os exemplos a seguir demonstram as áreas de armazenamento local, sync e session:

Local

chrome.storage.local.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.local.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

Sincronização

chrome.storage.sync.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.sync.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

Sessão

chrome.storage.session.set({ key: value }).then(() => {
  console.log("Value was set");
});

chrome.storage.session.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

Para acessar outras demonstrações da API Storage, use um dos exemplos a seguir:

Tipos

AccessLevel

Chrome 102 ou mais recente

O nível de acesso da área de armazenamento.

Tipo enumerado

"TRUSTED_CONTEXTS"
Especifica contextos originados da própria extensão.

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
Especifica contextos originados de fora da extensão.

StorageArea

Propriedades

  • onChanged

    Evento<functionvoid>

    Chrome 73 ou mais recente

    Disparado quando um ou mais itens são alterados.

    A função onChanged.addListener tem esta aparência: 

    (callback: function)=> {...}

    • callback

      função

      O parâmetro callback tem esta aparência: 

      (changes: object)=>void

      • Mudanças

        objeto

  • limpar

    void

    Promessa

    Remove todos os itens do armazenamento.

    A função clear tem esta aparência: 

    (callback?: function)=> {...}

    • callback

      função optional

      O parâmetro callback tem esta aparência: 

      ()=>void

    • retorna

      Promise<void>

      Chrome 88 ou mais recente

      Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

  • get

    void

    Promessa

    Recebe um ou mais itens do armazenamento.

    A função get tem esta aparência: 

    (keys?: string|string[]|object,callback?: function)=> {...}

    • chaves

      string|string[]|object optional

      Uma única chave para receber, uma lista de chaves a serem conseguidas ou um dicionário que especifica valores padrão (consulte a descrição do objeto). Uma lista ou um objeto vazio retornará um objeto de resultado vazio. Transmita null para receber todo o conteúdo do armazenamento.

    • callback

      função optional

      O parâmetro callback tem esta aparência: 

      (items: object)=>void

      • items

        objeto

        Objeto com itens nos respectivos mapeamentos de chave-valor.

    • retorna

      Promise<object>

      Chrome 88 ou mais recente

      Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

  • getBytesInUse

    void

    Promessa

    Recebe a quantidade de espaço (em bytes) sendo usado por um ou mais itens.

    A função getBytesInUse tem esta aparência: 

    (keys?: string|string[],callback?: function)=> {...}

    • chaves

      string|string[] optional

      Uma única chave ou lista de chaves para conferir o uso total. Uma lista vazia retornará 0. Transmita null para conferir o uso total de todo o armazenamento.

    • callback

      função optional

      O parâmetro callback tem esta aparência: 

      (bytesInUse: number)=>void

      • bytesInUse

        number

        Quantidade de espaço usado no armazenamento (em bytes).

    • retorna

      Prometer<número>

      Chrome 88 ou mais recente

      Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

  • remove

    void

    Promessa

    Remove um ou mais itens do armazenamento.

    A função remove tem esta aparência: 

    (keys: string|string[],callback?: function)=> {...}

    • chaves

      string|string[]

      Uma única chave ou uma lista de chaves para os itens removerem.

    • callback

      função optional

      O parâmetro callback tem esta aparência: 

      ()=>void

    • retorna

      Promise<void>

      Chrome 88 ou mais recente

      Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

  • set

    void

    Promessa

    Define vários itens.

    A função set tem esta aparência: 

    (items: object,callback?: function)=> {...}

    • items

      objeto

      Um objeto que fornece a cada par de chave-valor para atualizar o armazenamento. Nenhum outro par de chave-valor no armazenamento será afetado.

      Valores primitivos, como números, são serializados conforme esperado. Valores com typeof "object" e "function" normalmente são serializados para {}, com exceção de Array (serializa conforme esperado), Date e Regex (serializa usando a representação String deles).

    • callback

      função optional

      O parâmetro callback tem esta aparência: 

      ()=>void

    • retorna

      Promise<void>

      Chrome 88 ou mais recente

      Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

  • setAccessLevel

    void

    Promessa Chrome 102 ou mais recente

    Define o nível de acesso desejado para a área de armazenamento. O padrão será apenas contextos confiáveis.

    A função setAccessLevel tem esta aparência: 

    (accessOptions: object,callback?: function)=> {...}

    • accessOptions

      objeto

      • accessLevel

        AccessLevel

        O nível de acesso da área de armazenamento.

    • callback

      função optional

      O parâmetro callback tem esta aparência: 

      ()=>void

    • retorna

      Promise<void>

      Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

StorageChange

Propriedades

  • newValue

    Qualquer opção opcional

    Novo valor do item, se houver um novo valor.

  • oldValue

    Qualquer opção opcional

    Valor antigo do item, se havia um valor antigo.

Propriedades

local

Os itens na área de armazenamento de local são locais para cada máquina.

Tipo

StorageArea&object

Propriedades

  • QUOTA_BYTES

    10485760

    A quantidade máxima (em bytes) de dados que pode ser armazenada no armazenamento local, conforme medida pela string JSON de cada valor mais o comprimento de cada chave. Esse valor será ignorado se a extensão tiver a permissão unlimitedStorage. As atualizações que fariam com que esse limite fosse excedido falha imediatamente e define runtime.lastError ao usar um callback, ou uma promessa rejeitada se estiver usando async/await.

managed

Os itens na área de armazenamento do managed são definidos por uma política corporativa configurada pelo administrador do domínio e são somente leitura para a extensão. Tentar modificar esse namespace resulta em erro. Para saber mais sobre como configurar uma política, consulte Manifesto para áreas de armazenamento.

Tipo

StorageArea

session

Chrome 102+ MV3+

Os itens na área de armazenamento session são mantidos na memória e não serão mantidos no disco.

Tipo

StorageArea&object

Propriedades

  • QUOTA_BYTES

    10485760

    A quantidade máxima (em bytes) de dados que pode ser armazenada na memória, conforme medido pela estimativa do uso de memória alocada dinamicamente de cada valor e chave. As atualizações que fazem com que esse limite seja excedido falha imediatamente e define runtime.lastError ao usar um callback ou quando uma promessa é rejeitada.

sync

Os itens na área de armazenamento do sync são sincronizados usando a Sincronização do Chrome.

Tipo

StorageArea&object

Propriedades

  • MAX_ITEMS

    512

    O número máximo de itens que podem ser armazenados no armazenamento sincronizado. As atualizações que fariam com que esse limite fosse excedido vão falhar imediatamente e definir runtime.lastError ao usar um callback ou quando uma promessa for rejeitada.

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000.000

    Descontinuado

    A API storage.sync não tem mais uma cota de operação de gravação sustentada.

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1.800

    O número máximo de operações set, remove ou clear que podem ser realizadas a cada hora. Isso é 1 a cada 2 segundos, um teto menor do que o limite maior de gravações por minuto de curto prazo.

    As atualizações que fazem com que esse limite seja excedido falha imediatamente e define runtime.lastError ao usar um callback ou quando uma promessa é rejeitada.

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

    O número máximo de operações set, remove ou clear que podem ser realizadas a cada minuto. Isso é 2 por segundo, fornecendo maior capacidade do que as gravações por hora em um período mais curto.

    As atualizações que fazem com que esse limite seja excedido falha imediatamente e define runtime.lastError ao usar um callback ou quando uma promessa é rejeitada.

  • QUOTA_BYTES

    102400

    A quantidade total máxima (em bytes) de dados que pode ser armazenada no armazenamento sincronizado, conforme medida pela string JSON de cada valor mais o comprimento de cada chave. As atualizações que fazem com que esse limite seja excedido falha imediatamente e define runtime.lastError ao usar um callback ou quando uma promessa é rejeitada.

  • QUOTA_BYTES_PER_ITEM

    8.192

    O tamanho máximo (em bytes) de cada item individual no armazenamento sincronizado, conforme medido pela string JSON do valor mais o comprimento da chave. As atualizações com itens maiores que esse limite vão falhar imediatamente e definir runtime.lastError ao usar um callback ou quando uma promessa for rejeitada.

Eventos

onChanged

chrome.storage.onChanged.addListener(
  callback: function,
)

Disparado quando um ou mais itens são alterados.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (changes: object,areaName: string)=>void

    • Mudanças

      objeto

    • areaName

      string