chrome.storage

Descrição

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

Permissões

storage

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

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

Conceitos e uso

A API Storage fornece 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. 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 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 a navegação anônima dividida.
  • Inclui uma área de armazenamento gerenciado exclusivo somente leitura para políticas empresariais.

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 a recomendamos pelos seguintes motivos:

  • Os service workers de extensão não podem usar a API Web Storage.
  • Os scripts de conteúdo compartilham 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ão de um service worker:

  1. Prepare um arquivo de script e uma página html de documento fora da tela. O arquivo de script precisa conter uma rotina de conversão e um gerenciador onMessage.
  2. No service worker da 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 no funcionamento das APIs de armazenamento na Web nas extensões. Saiba mais na 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 anteriores), 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 de políticas e gerenciado por administradores de 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 de sistema, e não pelo 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 de 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 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 qualquer navegador Chrome em que o usuário tenha feito login. Se desativada, ela vai se comportar 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, 8 KB por item. Recomendamos o uso de storage.sync para preservar as configurações de usuário em navegadores sincronizados. Se você estiver trabalhando com dados confidenciais de usuários, use storage.session.

Limites de armazenamento e limitação

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

  • O armazenamento de dados costuma gerar custos de desempenho, e a API inclui cotas de armazenamento. Recomendamos ter cuidado com os dados armazenados para não perder a capacidade de armazenar dados.
  • O armazenamento pode levar algum tempo para ser concluído. Estruture seu código para considerar esse tempo.

Para mais detalhes sobre as limitações da á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 rastrear as alterações feitas no armazenamento, adicione um listener ao evento onChanged. Quando algo é alterado no armazenamento, esse evento é disparado. 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 que o usuário alterne 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 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 carregam de forma assíncrona os dados do armazenamento antes de executarem seus manipuladores de eventos. Para fazer isso, o O snippet a seguir usa um manipulador de eventos action.onClicked assíncrono que aguarda o storageCache global sejam preenchidos 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 APIs local, sync e session áreas de armazenamento:

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 ver outras demonstrações da API Storage, explore uma destas opções:

Tipos

AccessLevel

Chrome 102 ou versões mais recentes

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

Enumeração

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

&quot;TRUSTED_AND_UNTRUSTED_CONTEXTS&quot;
Especifica contextos originados de fora da extensão.

StorageArea

Propriedades

  • onChanged

    Evento<functionvoidvoid>

    Chrome 73 ou superior

    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

      • muda

        objeto

  • limpar

    void

    Promessa

    Remove todos os itens do armazenamento.

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

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

    • callback

      função opcional

      O parâmetro callback tem esta aparência: 

      () => void

    • retorna

      Promessa<void>

      Chrome 88 ou superior

      O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

  • 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[] | objeto opcional

      Uma única chave a ser recebida, uma lista de chaves a receber 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 opcional

      O parâmetro callback tem esta aparência: 

      (items: object) => void

      • itens

        objeto

        Objeto com itens nos mapeamentos de chave-valor.

    • retorna

      Promise&lt;object&gt;

      Chrome 88 ou superior

      O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

  • getBytesInUse

    void

    Promessa

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

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

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

    • chaves

      string | string[] opcional

      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 opcional

      O parâmetro callback tem esta aparência: 

      (bytesInUse: number) => void

      • bytesInUse

        number

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

    • retorna

      Promise&lt;number&gt;

      Chrome 88 ou superior

      O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

  • getKeys

    void

    Promessa Pendente

    Recebe todas as chaves do armazenamento.

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

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

    • callback

      função opcional

      O parâmetro callback tem esta aparência: 

      (keys: string[]) => void

      • chaves

        string[]

        Matriz com chaves lidas do armazenamento.

    • retorna

      Promise&lt;string[]&gt;

      O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

  • remover

    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 itens a serem removidos.

    • callback

      função opcional

      O parâmetro callback tem esta aparência: 

      () => void

    • retorna

      Promessa<void>

      Chrome 88 ou superior

      O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

  • set

    void

    Promessa

    Define vários itens.

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

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

    • itens

      objeto

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

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

    • callback

      função opcional

      O parâmetro callback tem esta aparência: 

      () => void

    • retorna

      Promessa<void>

      Chrome 88 ou superior

      O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

  • setAccessLevel

    void

    Promessa Chrome 102 ou versões mais recentes

    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 opcional

      O parâmetro callback tem esta aparência: 

      () => void

    • retorna

      Promessa<void>

      O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

StorageChange

Propriedades

  • newValue

    Qualquer opcional

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

  • oldValue

    Qualquer opcional

    Valor antigo do item, se houver um valor antigo.

Propriedades

local

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

Tipo

StorageArea e objeto

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 poderiam exceder esse limite falham imediatamente e definem runtime.lastError ao usar um callback ou uma promessa rejeitada se você 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 informações sobre como configurar uma política, consulte Manifesto para áreas de armazenamento.

Tipo

StorageArea

session

Chrome 102 ou versões mais recentes 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 pode ser armazenada na memória, medida pela estimativa do uso de memória alocada dinamicamente de cada valor e chave. As atualizações que poderiam exceder esse limite falham imediatamente e definem runtime.lastError ao usar um callback ou quando uma promessa é rejeitada.

sync

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

Tipo

StorageArea e objeto

Propriedades

  • MAX_ITEMS

    512

    O número máximo de itens que podem ser guardados no armazenamento sincronizado. As atualizações que fazem com que esse limite seja 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

    1.000.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 executadas a cada hora. Isso é 1 a cada 2 segundos, um teto menor do que o limite de gravações por minuto mais alto de curto prazo.

    As atualizações que poderiam exceder esse 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 executadas a cada minuto. Isso é 2 por segundo, proporcionando uma capacidade maior do que gravações por hora em um período mais curto.

    As atualizações que poderiam exceder esse 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 pode ser armazenada no armazenamento sincronizado, conforme medida pela string JSON de cada valor mais o comprimento de cada chave. As atualizações que poderiam exceder esse limite falham imediatamente e definem 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 que contêm itens acima desse 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

    • muda

      objeto

    • areaName

      string