Esta página foi traduzida pela API Cloud Translation.

chrome.storage

Descrição

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

Permissões

storage

Visão geral

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.

Embora as extensões possam usar a interface [Storage][mdn-storage] (acessível em window.localStorage) em alguns contextos (pop-up e outras páginas HTML), não é recomendável fazer isso 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 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 das APIs de armazenamento da Web para as APIs de armazenamento de extensão de um service worker:

Crie um documento fora da tela com uma rotina de conversão e um manipulador [onMessage][on-message].
Adiciona uma rotina de conversão a um documento fora da tela.
Na verificação do service worker da extensão, procure chrome.storage para seus dados.
Se os 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.
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][storage-and-cookies].

Áreas de armazenamento

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

storage.local: Os dados são armazenados localmente e são apagados quando a extensão é removida. A limitação de cota é de aproximadamente 10 MB, mas pode ser aumentada 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 qualquer navegador Chrome em que o usuário 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. Considere usar esse recurso para preservar as configurações do usuário em navegadores sincronizados.

Aviso:as áreas de armazenamento local e de sincronização não devem armazenar dados confidenciais do usuário porque não são criptografadas. Ao trabalhar com dados sensíveis, considere usar a área de armazenamento session para manter valores na memória até que o navegador seja fechado.

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 mudado definindo chrome.storage.session.setAccessLevel(). A limitação de cota é de aproximadamente 10 MB. Considere usá-lo para armazenar variáveis globais em execuções de service worker.

storage.managed: Os administradores podem usar um esquema e políticas empresariais para configurar as definições de uma extensão de suporte em um ambiente gerenciado. Essa á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 managed, consulte Manifesto para áreas de armazenamento.

Limites de armazenamento e de redução

Não pense em adicionar à API Storage como colocar coisas em um caminhão grande. Pense em adicionar ao armazenamento como colocar algo em um tubo. O cano pode já ter material dentro dele e até mesmo estar cheio. Sempre considere um atraso entre o momento em que você adiciona ao armazenamento e quando ele é realmente gravado.

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.

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 acompanhar as mudanças feitas no armazenamento, adicione um listener ao evento onChanged. 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 nem sempre estão em execução, as extensões do Manifesto 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);
});

Exemplos de extensões

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

Tipos

AccessLevel

Chrome 102 ou mais recente

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

Enumeração

"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

Event<functionvoidvoid>

Chrome 73 ou mais recente

Disparado quando um ou mais itens mudam.

A função onChanged.addListener é assim:
```
(callback: function) => {...}
```
- callback
  
  função
  
  O parâmetro callback tem esta aparência:
```
(changes: object) => void
```
  - muda
    
    objeto
limpar

void

Promise

Remove todos os itens do armazenamento.

A função clear é assim:
```
(callback?: function) => {...}
```
- callback
  
  função opcional
  
  O parâmetro callback tem esta aparência:
```
() => void
```
- retorna
  Promise<void>
  
  Chrome 95+
  
  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
get

void

Promise

Recebe um ou mais itens do armazenamento.

A função get é assim:
```
(keys?: string | string[] | object, callback?: function) => {...}
```
- chaves
  
  string | string[] | object opcional
  
  Uma única chave, uma lista de chaves 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 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<object>
  
  Chrome 95+
  
  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
getBytesInUse

void

Promise

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

A função getBytesInUse é assim:
```
(keys?: string | string[], callback?: function) => {...}
```
- chaves
  
  string | string[] opcional
  
  Uma única chave ou lista de chaves para receber o uso total. Uma lista vazia retorna 0. Transmita null para receber o uso total de todo o armazenamento.
- callback
  
  função opcional
  
  O parâmetro callback tem esta aparência:
```
(bytesInUse: number) => void
```
  - bytesInUse
    
    número
    
    Quantidade de espaço em uso no armazenamento, em bytes.
- retorna
  Promise<number>
  
  Chrome 95+
  
  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
getKeys

void

Promise Chrome 130 ou mais recente

Recebe todas as chaves do armazenamento.

A função getKeys é assim:
```
(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<string[]>
  
  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
remover

void

Promise

Remove um ou mais itens do armazenamento.

A função remove é assim:
```
(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
  Promise<void>
  
  Chrome 95+
  
  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
set

void

Promise

Define vários itens.

A função set é assim:
```
(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. Valores com um typeof "object" e "function" geralmente são serializados como {}, exceto Array (serializado como esperado), Date e Regex (serializados usando a representação String).
- callback
  
  função opcional
  
  O parâmetro callback tem esta aparência:
```
() => void
```
- retorna
  Promise<void>
  
  Chrome 95+
  
  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
setAccessLevel

void

Promise Chrome 102 ou mais recente

Define o nível de acesso desejado para a área de armazenamento. Por padrão, o armazenamento session é restrito a contextos confiáveis (páginas de extensão e service workers), enquanto o armazenamento local e sync permite acesso de contextos confiáveis e não confiáveis.

A função setAccessLevel é assim:
```
(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
  Promise<void>
  
  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

StorageChange

Propriedades

newValue

qualquer opcional

O novo valor do item, se houver.
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 serializaçã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 excederem esse limite vão falhar imediatamente e definir runtime.lastError ao usar um callback ou uma promessa rejeitada ao 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 informações sobre como configurar uma política, consulte Manifesto para áreas de armazenamento.

Tipo

StorageArea

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 excederem esse 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 por hora. Isso é 1 a cada 2 segundos, um limite inferior ao limite de gravações por minuto de curto prazo.

As atualizações que excederem esse limite vão falhar imediatamente e definir 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 equivale a 2 por segundo, o que oferece maior capacidade de processamento do que gravações por hora em um período mais curto.

As atualizações que excederem esse limite vão falhar imediatamente e definir 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 de sincronização, medida pela stringificação JSON de cada valor mais o comprimento de cada chave. As atualizações que excederem esse limite vão falhar imediatamente e definir 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 de sincronização, medido pela stringificação JSON do valor mais o comprimento da chave. As atualizações que contiverem 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 mudam.

Parâmetros

callback

função

O parâmetro callback tem esta aparência:
```
(changes: object, areaName: string) => void
```
- muda
  
  objeto
- areaName
  
  string

chrome.storage Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Descrição

Permissões

Visão geral

Áreas de armazenamento

Manifesto

Uso

storage.local

storage.sync

storage.session

Limites de armazenamento e de redução

Casos de uso

Resposta síncrona a atualizações de armazenamento

Pré-carregamento assíncrono do armazenamento

Exemplos de extensões

Tipos

AccessLevel

Enumeração

StorageArea

Propriedades

StorageChange

Propriedades

Propriedades

local

Tipo

Propriedades

managed

Tipo

sync

Tipo

Propriedades

Eventos

onChanged

Parâmetros

chrome.storage