Se usó la API de Cloud Translation para traducir esta página.

chrome.storage

Descripción

Usa la API de chrome.storage para almacenar, recuperar y hacer un seguimiento de los cambios en los datos del usuario.

Permisos

storage

Para usar la API de almacenamiento, declara el permiso "storage" en el manifiesto de la extensión. Por ejemplo:

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

Conceptos y uso

La API de Storage proporciona una forma específica de la extensión para conservar los datos y el estado del usuario. Es similar a las APIs de almacenamiento de la plataforma web (IndexedDB y Storage), pero se diseñó para satisfacer las necesidades de almacenamiento de las extensiones. Estas son algunas de sus funciones clave:

Todos los contextos de la extensión, incluido el trabajador de servicio de la extensión y las secuencias de comandos del contenido, tienen acceso a la API de Storage.
Los valores serializables de JSON se almacenan como propiedades de objetos.
La API de Storage es asíncrona con operaciones de lectura y escritura masivas.
Incluso si el usuario borra la caché y el historial de navegación, los datos persisten.
La configuración almacenada persiste incluso cuando se usa el modo Incógnito dividido.
Incluye un área de almacenamiento administrada de solo lectura exclusivo para las políticas empresariales.

¿Las extensiones pueden usar APIs de almacenamiento web?

Si bien las extensiones pueden usar la interfaz Storage (a la que se puede acceder desde window.localStorage) en algunos contextos (ventanas emergentes y otras páginas HTML), no lo recomendamos por los siguientes motivos:

Los service workers de extensiones no pueden usar la API de Web Storage.
Las secuencias de comandos de contenido comparten el almacenamiento con la página host.
Los datos guardados con la API de Web Storage se pierden cuando el usuario borra su historial de navegación.

Para mover datos de las APIs de almacenamiento web a las APIs de almacenamiento de extensiones desde un service worker, haz lo siguiente:

Prepara una página HTML y un archivo de secuencia de comandos del documento fuera de pantalla. El archivo de secuencia de comandos debe contener una rutina de conversión y un controlador onMessage.
En el trabajador del servicio de extensión, busca tus datos en chrome.storage.
Si no se encuentran tus datos, llama a createDocument().
Una vez que se resuelva la promesa que se muestra, llama a sendMessage() para iniciar la rutina de conversión.
Dentro del controlador onMessage del documento fuera de pantalla, llama a la rutina de conversión.

También hay algunos matices en el funcionamiento de las APIs de almacenamiento web en las extensiones. Obtén más información en el artículo Almacenamiento y cookies.

Áreas de almacenamiento

La API de Storage se divide en las siguientes áreas de almacenamiento:

storage.local: Los datos se almacenan de forma local y se borran cuando se quita la extensión. El límite de almacenamiento es de 10 MB (5 MB en Chrome 113 y versiones anteriores), pero se puede aumentar si se solicita el permiso "unlimitedStorage". Recomendamos usar storage.local para almacenar grandes cantidades de datos.
storage.managed: El almacenamiento administrado es de solo lectura para las extensiones instaladas por políticas y es administrado por los administradores del sistema con un esquema definido por el desarrollador y políticas empresariales. Las políticas son similares a las opciones, pero un administrador del sistema las configura en lugar del usuario, lo que permite que la extensión se preconfigure para todos los usuarios de una organización. Para obtener información sobre las políticas, consulta la Documentación para administradores. Para obtener más información sobre el área de almacenamiento managed, consulta Manifiesto para áreas de almacenamiento.
storage.session: Contiene datos en la memoria durante una sesión del navegador. De forma predeterminada, no se expone a las secuencias de comandos de contenido, pero se puede cambiar este comportamiento configurando chrome.storage.session.setAccessLevel(). El límite de almacenamiento es de 10 MB (1 MB en Chrome 111 y versiones anteriores). La interfaz storage.session es una de las varias que recomendamos para los trabajadores del servicio.
storage.sync: Si la sincronización está habilitada, los datos se sincronizan con cualquier navegador Chrome al que haya accedido el usuario. Si está inhabilitada, se comporta como storage.local. Chrome almacena los datos de forma local cuando el navegador no tiene conexión y reanuda la sincronización cuando vuelve a estar en línea. La limitación de cuota es de aproximadamente 100 KB, 8 KB por elemento. Te recomendamos que uses storage.sync para preservar la configuración del usuario en los navegadores sincronizados. Si trabajas con datos sensibles del usuario, usa storage.session.

Límites de almacenamiento y regulación

La API de Storage tiene las siguientes limitaciones de uso:

El almacenamiento de datos suele tener costos de rendimiento, y la API incluye cuotas de almacenamiento. Te recomendamos que tengas cuidado con los datos que almacenas para no perder la capacidad de almacenarlos.
El almacenamiento puede tardar en completarse. Asegúrate de estructurar tu código para tener en cuenta ese tiempo.

Para obtener detalles sobre las limitaciones del área de almacenamiento y lo que sucede cuando se superan, consulta la información de cuotas de sync, local y session.

Casos de uso

En las siguientes secciones, se muestran casos de uso comunes de la API de Storage.

Respuesta síncrona a las actualizaciones de almacenamiento

Para hacer un seguimiento de los cambios realizados en el almacenamiento, agrega un objeto de escucha a su evento onChanged. Cuando cambia algo en el almacenamiento, se activa ese evento. El código de muestra detecta estos cambios:

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 llevar esta idea aún más lejos. En este ejemplo, tenemos una página de opciones que le permite al usuario activar o desactivar un "modo de depuración" (la implementación no se muestra aquí). La página de opciones guarda inmediatamente la configuración nueva en storage.sync, y el trabajador del servicio usa storage.onChanged para aplicar la configuración lo antes posible.

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);
  }
});

Carga previa asíncrona desde el almacenamiento

Debido a que los trabajadores del servicio no se ejecutan todo el tiempo, las extensiones de manifiesto V3 a veces deben cargar datos de forma asíncrona desde el almacenamiento antes de ejecutar sus controladores de eventos. Para ello, el siguiente fragmento usa un controlador de eventos action.onClicked asíncrono que espera a que se propague el elemento storageCache global antes de ejecutar su 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);
});

Ejemplos

En los siguientes ejemplos, se muestran las áreas de almacenamiento local, sync y 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);
});

Sincronizar

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);
});

Sesión

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 otras demostraciones de la API de Storage, explora cualquiera de las siguientes muestras:

Tipos

AccessLevel

Chrome 102 y versiones posteriores

Es el nivel de acceso del área de almacenamiento.

Enum

"TRUSTED_CONTEXTS"
Especifica los contextos que provienen de la extensión.

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
Especifica los contextos que provienen de fuera de la extensión.

StorageArea

Propiedades

onChanged

Event<functionvoidvoid>

Chrome 73 y versiones posteriores

Se activa cuando cambia uno o más elementos.

La función onChanged.addListener se ve de la siguiente manera:
```
(callback: function) => {...}
```
- callback
  
  función
  
  El parámetro callback se ve de la siguiente manera:
```
(changes: object) => void
```
  - Cambios
    
    objeto
borrar

void

Promesa

Quita todos los elementos del almacenamiento.

La función clear se ve de la siguiente manera:
```
(callback?: function) => {...}
```
- callback
  
  función opcional
  
  El parámetro callback se ve de la siguiente manera:
```
() => void
```
- muestra
  Promise<void>
  
  Chrome 88 y versiones posteriores
  
  Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
get

void

Promesa

Obtiene uno o más elementos del almacenamiento.

La función get se ve de la siguiente manera:
```
(keys?: string | string[] | object, callback?: function) => {...}
```
- claves
  
  cadena | cadena[] | objeto opcional
  
  Una sola clave para obtener, una lista de claves para obtener o un diccionario que especifique valores predeterminados (consulta la descripción del objeto). Una lista o un objeto vacíos mostrarán un objeto de resultado vacío. Pasa null para obtener todo el contenido del almacenamiento.
- callback
  
  función opcional
  
  El parámetro callback se ve de la siguiente manera:
```
(items: object) => void
```
  - elementos
    
    objeto
    
    Objeto con elementos en sus asignaciones de pares clave-valor.
- muestra
  Promise<object>
  
  Chrome 88 y versiones posteriores
  
  Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
getBytesInUse

void

Promesa

Obtiene la cantidad de espacio (en bytes) que usan uno o más elementos.

La función getBytesInUse se ve de la siguiente manera:
```
(keys?: string | string[], callback?: function) => {...}
```
- claves
  
  cadena | cadena[] opcional
  
  Una sola clave o una lista de claves para obtener el uso total. Una lista vacía mostrará 0. Pasa null para obtener el uso total de todo el almacenamiento.
- callback
  
  función opcional
  
  El parámetro callback se ve de la siguiente manera:
```
(bytesInUse: number) => void
```
  - bytesInUse
    
    número
    
    Es la cantidad de espacio que se usa en el almacenamiento, en bytes.
- muestra
  Promise<number>
  
  Chrome 88 y versiones posteriores
  
  Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
getKeys

void

Promesa Chrome 130 y versiones posteriores

Obtiene todas las claves del almacenamiento.

La función getKeys se ve de la siguiente manera:
```
(callback?: function) => {...}
```
- callback
  
  función opcional
  
  El parámetro callback se ve de la siguiente manera:
```
(keys: string[]) => void
```
  - claves
    
    string[]
    
    Es un array con claves leídas del almacenamiento.
- muestra
  Promise<string[]>
  
  Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
quitar

void

Promesa

Quita uno o más elementos del almacenamiento.

La función remove se ve de la siguiente manera:
```
(keys: string | string[], callback?: function) => {...}
```
- claves
  
  cadena | cadena[]
  
  Una sola clave o una lista de claves de los elementos que se quitarán.
- callback
  
  función opcional
  
  El parámetro callback se ve de la siguiente manera:
```
() => void
```
- muestra
  Promise<void>
  
  Chrome 88 y versiones posteriores
  
  Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
set

void

Promesa

Establece varios elementos.

La función set se ve de la siguiente manera:
```
(items: object, callback?: function) => {...}
```
- elementos
  
  objeto
  
  Un objeto que proporciona cada par clave-valor para actualizar el almacenamiento. No se verán afectados los demás pares clave-valor en el almacenamiento.
  
  Los valores primitivos, como los números, se serializarán como se espera. Por lo general, los valores con typeof "object" y "function" se serializan en {}, con la excepción de Array (se serializa como se espera), Date y Regex (se serializa con su representación String).
- callback
  
  función opcional
  
  El parámetro callback se ve de la siguiente manera:
```
() => void
```
- muestra
  Promise<void>
  
  Chrome 88 y versiones posteriores
  
  Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
setAccessLevel

void

Promesa Chrome 102 y versiones posteriores

Establece el nivel de acceso deseado para el área de almacenamiento. La configuración predeterminada solo incluirá contextos de confianza.

La función setAccessLevel se ve de la siguiente manera:
```
(accessOptions: object, callback?: function) => {...}
```
- accessOptions
  
  objeto
  - accessLevel
    
    AccessLevel
    
    Es el nivel de acceso del área de almacenamiento.
- callback
  
  función opcional
  
  El parámetro callback se ve de la siguiente manera:
```
() => void
```
- muestra
  Promise<void>
  
  Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

StorageChange

Propiedades

newValue

cualquier opcional

El valor nuevo del elemento, si hay uno.
oldValue

cualquier opcional

El valor anterior del elemento, si había uno.

Propiedades

local

Los elementos del área de almacenamiento local son locales para cada máquina.

Tipo

StorageArea y objeto

Propiedades

QUOTA_BYTES

10485760

Es la cantidad máxima (en bytes) de datos que se puede almacenar en el almacenamiento local, medida por la conversión de cadena JSON de cada valor más la longitud de cada clave. Este valor se ignorará si la extensión tiene el permiso unlimitedStorage. Las actualizaciones que provocarían que se exceda este límite fallan de inmediato y establecen runtime.lastError cuando se usa una devolución de llamada o una promesa rechazada si se usa async/await.

managed

Los elementos del área de almacenamiento managed se establecen mediante una política empresarial que configura el administrador del dominio y son de solo lectura para la extensión. Si intentas modificar este espacio de nombres, se producirá un error. Para obtener información sobre cómo configurar una política, consulta Manifiesto para áreas de almacenamiento.

Tipo

StorageArea

session

Chrome 102 y versiones posteriores MV3 y versiones posteriores

Los elementos del área de almacenamiento session se almacenan en la memoria y no se conservan en el disco.

Tipo

StorageArea y objeto

Propiedades

QUOTA_BYTES

10485760

Es la cantidad máxima (en bytes) de datos que se pueden almacenar en la memoria, medida mediante la estimación del uso de memoria asignado de forma dinámica de cada valor y clave. Las actualizaciones que provocarían que se exceda este límite fallan de inmediato y establecen runtime.lastError cuando se usa una devolución de llamada o cuando se rechaza una promesa.

sync

Los elementos del área de almacenamiento sync se sincronizan con la Sincronización de Chrome.

Tipo

StorageArea y objeto

Propiedades

MAX_ITEMS

512

Es la cantidad máxima de elementos que se pueden almacenar en el almacenamiento sincronizado. Las actualizaciones que superen este límite fallarán de inmediato y establecerán runtime.lastError cuando se use una devolución de llamada o cuando se rechace una promesa.
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

1000000

Obsoleto

La API de storage.sync ya no tiene una cuota de operación de escritura continua.
MAX_WRITE_OPERATIONS_PER_HOUR

1800

Es la cantidad máxima de operaciones set, remove o clear que se pueden realizar cada hora. Esto es 1 cada 2 segundos, un límite inferior que el límite más alto de operaciones de escritura por minuto a corto plazo.

Las actualizaciones que provocarían que se exceda este límite fallan de inmediato y establecen runtime.lastError cuando se usa una devolución de llamada o cuando se rechaza una promesa.
MAX_WRITE_OPERATIONS_PER_MINUTE

120

Es la cantidad máxima de operaciones set, remove o clear que se pueden realizar por minuto. Esto es 2 por segundo, lo que proporciona una mayor capacidad de procesamiento que las operaciones de escritura por hora en un período más corto.

Las actualizaciones que provocarían que se exceda este límite fallan de inmediato y establecen runtime.lastError cuando se usa una devolución de llamada o cuando se rechaza una promesa.
QUOTA_BYTES

102400

Es la cantidad total máxima (en bytes) de datos que se pueden almacenar en el almacenamiento sincronizado, medida por la conversión de cadena JSON de cada valor más la longitud de cada clave. Las actualizaciones que provocarían que se exceda este límite fallan de inmediato y establecen runtime.lastError cuando se usa una devolución de llamada o cuando se rechaza una promesa.
QUOTA_BYTES_PER_ITEM

8192

Es el tamaño máximo (en bytes) de cada elemento individual en el almacenamiento sincronizado, medido por la conversión de cadena JSON de su valor más la longitud de su clave. Las actualizaciones que contengan elementos mayores que este límite fallarán de inmediato y establecerán runtime.lastError cuando se use una devolución de llamada o cuando se rechace una promesa.

Eventos

onChanged

chrome.storage.onChanged.addListener(
  callback: function,
)

Se activa cuando cambia uno o más elementos.

Parámetros

callback

función

El parámetro callback se ve de la siguiente manera:
```
(changes: object, areaName: string) => void
```
- Cambios
  
  objeto
- areaName
  
  string