Descrição
Use a API chrome.storage
para armazenar, extrair e rastrear 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 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.
Extensões podem usar APIs de armazenamento da Web?
Embora as extensões possam usar a interface Storage
(acessível de window.localStorage
) em alguns contextos (pop-ups e outras páginas HTML), não recomendamos esse uso 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 de APIs de armazenamento da Web para APIs de armazenamento de extensões de um service worker:
- 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 gerenciador
onMessage
. - No service worker de extensão, verifique seus dados em
chrome.storage
. - Se os dados não forem encontrados, chame
createDocument()
. - Depois que a promessa retornada for resolvida, chame
sendMessage()
para iniciar a rotina de conversão. - 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.
Á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 anterior), mas pode ser aumentado solicitando a permissão
"unlimitedStorage"
. Recomendamos o uso destorage.local
para armazenar grandes quantidades de dados. storage.managed
- O armazenamento gerenciado é um armazenamento somente leitura para extensões instaladas em políticas e gerenciado por administradores do 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 do 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. Para mais informações sobre políticas, consulte Documentação para administradores. Para saber mais sobre a área de armazenamento do
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-se
chrome.storage.session.setAccessLevel()
. O limite de armazenamento é de 10 MB (1 MB no Chrome 111 e versões anteriores). A interfacestorage.session
é uma das várias recomendadas para service workers. 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. Recomendamos o uso destorage.sync
para preservar as configurações do usuário nos navegadores sincronizados. Se você estiver trabalhando com dados sensíveis do usuário, usestorage.session
.
Limites de armazenamento e limitaçã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 armazená-los.
- O armazenamento pode levar algum tempo para ser concluído. Organize seu código para considerar esse tempo.
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 do 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 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 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
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 acessar outras demonstrações da API Storage, use um dos exemplos a seguir:
Tipos
AccessLevel
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 recenteDisparado 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
PromessaRemove 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 recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
-
-
get
void
PromessaRecebe 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 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 recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
-
-
getBytesInUse
void
PromessaRecebe 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[] 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 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 recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
-
-
remove
void
PromessaRemove 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 recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
-
-
set
void
PromessaDefine 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 deArray
(serializa conforme esperado),Date
eRegex
(serializa usando a representaçãoString
deles). -
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
-
retorna
Promise<void>
Chrome 88 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
-
-
setAccessLevel
void
Promessa Chrome 102 ou mais recenteDefine 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
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 com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
-
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 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 fariam com que esse limite fosse excedido falha imediatamente e defineruntime.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
session
Os itens na área de armazenamento session
são mantidos na memória e não serã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, 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 e objeto
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
DescontinuadoA 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
ouclear
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
ouclear
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
-