chrome.storage

Descrição

Use a API chrome.storage para armazenar, recuperar e acompanhar as 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 oferece uma maneira específica da extensão para 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 recursos importantes:

  • Todos os contextos de extensão, incluindo o worker de serviço de extensão e os scripts de conteúdo, 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 persistir.
  • As configurações armazenadas são mantidas mesmo ao usar a navegação anônima dividida.
  • Inclui uma área de armazenamento gerenciado exclusiva somente leitura para políticas corporativas.

As extensões podem usar APIs de armazenamento na 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 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 das APIs de armazenamento da Web para as APIs de armazenamento de extensão de um service worker:

  1. Prepare uma página HTML e um arquivo de script do documento fora da tela. O arquivo de script precisa conter uma rotina de conversão e um manipulador onMessage.
  2. No worker de serviço de extensão, verifique chrome.storage para 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. Chame a rotina de conversão no manipulador onMessage do documento fora da tela.

Também há algumas nuances sobre 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 versões anteriores), mas pode ser aumentado solicitando a permissão "unlimitedStorage". Recomendamos o uso de storage.local para armazenar quantidades maiores de dados.
storage.managed
O armazenamento gerenciado é de leitura somente para extensões instaladas pela política e gerenciado por administradores do sistema usando um esquema definido pelo desenvolvedor e políticas corporativas. As políticas são análogas às opções, mas são configuradas por um administrador do sistema em vez do usuário, permitindo que a extensão seja pré-configurada para todos os usuários de uma organização. Para informações sobre políticas, consulte a Documentação para administradores. Para saber mais sobre a área de armazenamento managed, consulte Manifesto para áreas de armazenamento.
storage.session
Armazena dados na memória durante a sessão do navegador. Por padrão, ele não é exposto a scripts de conteúdo, mas esse comportamento pode ser alterado definindo 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.
storage.sync
Se a sincronização estiver ativada, os dados serão sincronizados com qualquer navegador Chrome em que o usuário fizer login. Se desativado, ele se comporta 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 o uso de storage.sync para preservar as configurações do usuário em todos os navegadores sincronizados. Se você estiver trabalhando com dados sensíveis do usuário, use storage.session.

Limites de armazenamento e restriçã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 armazenamento.
  • O armazenamento pode levar algum tempo para ser concluído. Estruture seu código para considerar esse tempo.

Para detalhes sobre as 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.

Casos de uso

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

Resposta síncrona a atualizações de armazenamento

Para acompanhar as mudanças feitas no armazenamento, adicione um listener ao evento onChanged. Quando algo muda no armazenamento, esse evento é acionado. O exemplo de código detecta 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 levar essa ideia ainda mais longe. Neste exemplo, temos uma página de opções que permite ao usuário ativar 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 worker do serviço 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 workers de serviço 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 executar os manipuladores de eventos. Para fazer isso, o fragmento a seguir usa um manipulador de eventos action.onClicked assíncrono que aguarda a população da variável 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 conferir outras demonstrações da API Storage, confira um dos seguintes exemplos:

Tipos

AccessLevel

Chrome 102 e versões mais recentes

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

Enumeração

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

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
especifica contextos originados fora da extensão.

StorageArea

Propriedades

  • onChanged

    Evento<functionvoidvoid>

    Chrome 73 e versões mais recentes

    Acionado quando um ou mais itens mudam.

    A função onChanged.addListener é semelhante a esta: 

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

    • callback

      função

      O parâmetro callback tem este formato: 

      (changes: object) => void

      • muda

        objeto

  • limpar

    void

    Promessa

    Remove todos os itens do armazenamento.

    A função clear é semelhante a esta: 

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

    • callback

      função opcional

      O parâmetro callback tem este formato: 

      () => void

    • retorna

      Promise<void>

      Chrome 88 e versões mais recentes

      As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

  • get

    void

    Promessa

    Recupera um ou mais itens do armazenamento.

    A função get é semelhante a esta: 

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

    • chaves

      string | string[] | object optional

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

    • callback

      função opcional

      O parâmetro callback tem este formato: 

      (items: object) => void

      • itens

        objeto

        Objeto com itens nos mapeamentos de chave-valor.

    • retorna

      Promise<object>

      Chrome 88 e versões mais recentes

      As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

  • getBytesInUse

    void

    Promessa

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

    A função getBytesInUse é semelhante a esta: 

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

    • chaves

      string | string[] opcional

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

    • callback

      função opcional

      O parâmetro callback tem este formato: 

      (bytesInUse: number) => void

      • bytesInUse

        number

        Quantidade de espaço usada no armazenamento, em bytes.

    • retorna

      Promise<number>

      Chrome 88 e versões mais recentes

      As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

  • getKeys

    void

    Promessa Chrome 130+

    Consegue todas as chaves do armazenamento.

    A função getKeys é semelhante a esta: 

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

    • callback

      função opcional

      O parâmetro callback tem este formato: 

      (keys: string[]) => void

      • chaves

        string[]

        Matriz com chaves lidas do armazenamento.

    • retorna

      Promise<string[]>

      As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

  • remover

    void

    Promessa

    Remove um ou mais itens do armazenamento.

    A função remove é semelhante a esta: 

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

    • chaves

      string | string[]

      Uma única chave ou uma lista de chaves para itens a serem removidos.

    • callback

      função opcional

      O parâmetro callback tem este formato: 

      () => void

    • retorna

      Promise<void>

      Chrome 88 e versões mais recentes

      As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

  • set

    void

    Promessa

    Define vários itens.

    A função set é semelhante a esta: 

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

    • itens

      objeto

      Um objeto que fornece cada par de chave-valor para atualizar o armazenamento. Os outros pares de chave-valor no armazenamento não serão afetados.

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

    • callback

      função opcional

      O parâmetro callback tem este formato: 

      () => void

    • retorna

      Promise<void>

      Chrome 88 e versões mais recentes

      As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

  • setAccessLevel

    void

    Promessa Chrome 102+

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

    A função setAccessLevel é semelhante a esta: 

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

    • accessOptions

      objeto

      • accessLevel

        AccessLevel

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

    • callback

      função opcional

      O parâmetro callback tem este formato: 

      () => void

    • retorna

      Promise<void>

      As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

StorageChange

Propriedades

  • newValue

    qualquer opcional

    O novo valor do item, se houver um novo valor.

  • oldValue

    qualquer opcional

    O valor antigo do item, se houver.

Propriedades

local

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

Tipo

StorageArea e objeto

Propriedades

  • QUOTA_BYTES

    10485760

    A quantidade máxima (em bytes) de dados que podem ser armazenados no armazenamento local, medida pela stringificação 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 causariam o estouro desse limite falham imediatamente e definem runtime.lastError ao usar um callback ou uma promessa rejeitada se você usar async/await.

managed

Os itens na área de armazenamento managed são definidos por uma política empresarial configurada pelo administrador do domínio e são somente leitura para a extensão. Tentar modificar esse namespace resulta em um erro. Para saber 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 armazenados na memória e não são mantidos no disco.

Tipo

StorageArea e objeto

Propriedades

  • QUOTA_BYTES

    10485760

    A quantidade máxima (em bytes) de dados que podem ser armazenados na memória, medida pela estimativa do uso de memória alocado dinamicamente de cada valor e chave. As atualizações que causariam o excesso desse limite falham imediatamente e definem runtime.lastError ao usar um callback ou quando uma promessa é rejeitada.

sync

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

Tipo

StorageArea e objeto

Propriedades

  • MAX_ITEMS

    512

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

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    Descontinuado

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

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1800

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

    As atualizações que causariam o excesso desse limite falham imediatamente e definem 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, oferecendo uma capacidade maior do que as gravações por hora em um período mais curto.

    As atualizações que causariam o excesso desse limite falham imediatamente e definem runtime.lastError ao usar um callback ou quando uma promessa é rejeitada.

  • QUOTA_BYTES

    102400

    A quantidade total máxima (em bytes) de dados que podem ser armazenados no armazenamento em sincronia, medida pela stringificação JSON de cada valor mais o comprimento de cada chave. As atualizações que causariam o excesso desse limite falham imediatamente e definem runtime.lastError ao usar um callback ou quando uma promessa é rejeitada.

  • QUOTA_BYTES_PER_ITEM

    8192

    O tamanho máximo (em bytes) de cada item individual no armazenamento em sincronização, medido pela stringificação 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,
)

Acionado quando um ou mais itens mudam.

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

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

    • muda

      objeto

    • areaName

      string