chrome.storage

Descrição

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

Permissões

storage

Visão geral

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.

Embora as extensões possam usar a interface [Storage][mdn-storage] (acessível de window.localStorage) em alguns contextos (pop-up e outras páginas HTML), ela não é recomendada pelos seguintes motivos:

  • O service worker da extensão não pode acessar Storage.
  • Os scripts de conteúdo compartilham o armazenamento com a página do host.
  • Os dados salvos usando a interface 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. Crie um documento fora da tela com uma rotina de conversão e um gerenciador [onMessage][on-message].
  2. Adicione uma rotina de conversão a um documento fora da tela.
  3. No service worker de extensão, verifique seus dados em chrome.storage.
  4. Se seus dados não forem encontrados, [crie][create-offscreen] um documento fora da tela e chame [sendMessage()][send-message] 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][armazenamento e cookies].

Áreas de armazenamento

A API Storage é dividida nos quatro buckets a seguir ("áreas de armazenamento"):

storage.local
Os dados são armazenados localmente, o que é apagado quando a extensão é removida. O limite de cota é de aproximadamente 10 MB, mas pode ser aumentado solicitando a permissão "unlimitedStorage". Considere usá-lo para armazenar grandes quantidades de dados.
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. Use esse recurso para preservar as configurações do usuário nos navegadores sincronizados.
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 cota é de aproximadamente 10 MB. Considere usá-lo para armazenar variáveis globais nas execuções de service worker.
storage.managed
Os administradores podem usar um esquema e políticas corporativas para definir as configurações de uma extensão de suporte em um ambiente gerenciado. Esta área de armazenamento é somente leitura.

Manifesto

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

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

Uso

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

storage.local

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

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

storage.sync

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

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

storage.session

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

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

Para saber mais sobre a área de armazenamento do managed, consulte Manifesto para áreas de armazenamento.

Limites de armazenamento e limitação

Não pense que o acréscimo à API Storage é como colocar itens em um caminhão grande. Pense na adição ao armazenamento como como colocar algo em um pipe. O cano pode já ter material e até estar preenchido. Sempre presuma um atraso entre o momento em que você adiciona armazenamento e quando ele é realmente gravado.

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 para 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 nem sempre estão em execução, às vezes as extensões do Manifest V3 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 de extensão

Para acessar outras demonstrações da API Storage, veja 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 apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

  • 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 apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

  • 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 apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

  • 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 apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

  • 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 apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

  • 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 apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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