chrome.storage

Descrição

Permissões

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

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

Exemplos

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

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);
});

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);
});

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

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

Para conferir outras demonstrações da API Storage, confira qualquer um dos exemplos a seguir:

• Extensão de pesquisa global.
• Extensão de alarme de água.

Conceitos e uso

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

• Todos os contextos de extensão, incluindo o service worker e os scripts de conteúdo da extensão, têm acesso à API Storage.
• Os valores serializáveis em JSON são armazenados como propriedades de 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 permanecer.
• As configurações armazenadas permanecem mesmo ao usar a navegação anônima dividida.
• Inclui uma área de armazenamento gerenciada exclusiva somente leitura para políticas empresariais.

As extensões podem usar APIs de armazenamento da Web?

Embora as extensões possam usar a interface Storage (acessível em window.localStorage) em alguns contextos (pop-up e outras páginas HTML), não recomendamos isso 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 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 das APIs de armazenamento da Web para as APIs de armazenamento de extensão 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 manipulador onMessage.
2. No service worker da extensão, verifique chrome.storage para conferir seus dados.
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. Dentro do manipulador onMessage do documento fora da tela, chame a rotina de conversão.

Também há algumas nuances sobre como as APIs de armazenamento da Web funcionam em extensões. Saiba mais no artigo Armazenamento e cookies.

Limites de armazenamento e limitação

A API Storage tem limitações de uso:

• O armazenamento de dados tem custos de desempenho, e a API inclui cotas de armazenamento. Planeje os dados que você pretende armazenar para manter o espaço de armazenamento.
• O armazenamento pode levar algum tempo para ser concluído. Estruture seu código para considerar esse tempo.

Para detalhes sobre limitações de área de armazenamento e o que acontece quando elas são excedidas, consulte as informações de cota para sync, local e session.

Áreas de armazenamento

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

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 versões anteriores), mas pode ser aumentado se você solicitar a permissão "unlimitedStorage". Recomendamos usar o storage.local para armazenar quantidades maiores de dados. Por padrão, ele é exposto a scripts de conteúdo, mas esse comportamento pode ser mudado chamando chrome.storage.local.setAccessLevel().

Gerenciado

O armazenamento gerenciado é somente leitura para extensões instaladas por políticas. Ele é gerenciado por administradores de 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 de 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.

Por padrão, storage.managed é exposto a scripts de conteúdo, mas esse comportamento pode ser mudado chamando chrome.storage.managed.setAccessLevel(). Para informações sobre políticas, consulte Documentação para administradores. Para saber mais sobre a área de armazenamento managed, consulte Manifesto para áreas de armazenamento.

Sessão

O armazenamento de sessão retém dados na memória enquanto uma extensão está carregada. O armazenamento é limpo se a extensão for desativada, recarregada, atualizada e quando o navegador for reiniciado. Por padrão, ele não é exposto a scripts de conteúdo, mas esse comportamento pode ser mudado chamando 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 que recomendamos para service workers.

Sincronização

Se o usuário ativar a sincronização, os dados serão sincronizados com todos os navegadores Chrome em que ele fizer login. Se estiver desativado, ele vai se comportar como storage.local. O Chrome armazena os dados localmente quando o navegador está off-line e retoma a sincronização quando ele volta a ficar on-line. A limitação de cota é de aproximadamente 100 KB, 8 KB por item.

Recomendamos usar storage.sync para preservar as configurações do usuário em navegadores sincronizados. Se você estiver trabalhando com dados sensíveis do usuário, use storage.session. Por padrão, storage.sync é exposto a scripts de conteúdo, mas esse comportamento pode ser mudado chamando chrome.storage.sync.setAccessLevel().

Métodos e eventos

Todas as áreas de armazenamento implementam a interface StorageArea.

get()

O método get() permite ler uma ou mais chaves de um StorageArea.

getBytesInUse()

O método getBytesInUse() permite consultar a cota usada por um StorageArea.

getKeys()

O método getKeys() permite acessar todas as chaves armazenadas em um StorageArea.

remove()

O método remove() permite remover um item de um StorageArea.

set()

O método set() permite definir um item em um StorageArea.

setAccessLevel()

O método setAccessLevel() permite controlar o acesso a um StorageArea.

clear()

O método clear() permite limpar todos os dados de um StorageArea.

onChanged

O evento onChanged permite monitorar mudanças em um StorageArea.

Casos de uso

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

Responder a atualizações de armazenamento

Para rastrear as mudanças feitas no armazenamento, adicione um listener ao evento onChanged dele. Quando algo muda no armazenamento, esse evento é disparado. O exemplo de código fica atento a estas mudanças:

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 ir ainda mais longe com essa ideia. Neste exemplo, temos uma página de opções que permite ao usuário ativar ou desativar um "modo de depuração" (a 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 assim que 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 de forma assíncrona do armazenamento antes de executar os manipuladores de eventos. Para isso, o snippet a seguir usa um manipulador de eventos action.onClicked assíncrono que aguarda o preenchimento do storageCache global 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);
});

DevTools

É possível ver e editar os dados armazenados usando a API no DevTools. Para saber mais, consulte a página Ver e editar o armazenamento de extensões na documentação do DevTools.

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