chrome.storage

Descripción

Permisos

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

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

Ejemplos

En los siguientes ejemplos, se muestran las áreas de almacenamiento local, sync y session:

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

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

chrome.storage.session.set({ key: value }).then(() => {
  console.log("Value is 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 los siguientes ejemplos:

• Extensión de búsqueda global
• Extensión de alarma de agua

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 extensión, incluidos el trabajador de servicio de la extensión y las secuencias de comandos de contenido, tienen acceso a la API de Storage.
• Los valores serializables en JSON se almacenan como propiedades de objetos.
• La API de Storage es asíncrona y admite operaciones de lectura y escritura masivas.
• Los datos persisten incluso si el usuario borra la caché y el historial de navegación.
• Los parámetros de configuración almacenados persisten incluso cuando se usa el modo Incógnito dividido.
• Incluye un área de almacenamiento administrada exclusiva de solo lectura para las políticas empresariales.

¿Pueden las extensiones usar las APIs de almacenamiento web?

Si bien las extensiones pueden usar la interfaz Storage (accesible desde window.localStorage) en algunos contextos (páginas emergentes y otras páginas HTML), no la 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 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:

1. Prepara una página HTML y un archivo de secuencia de comandos para el documento fuera de pantalla. El archivo de secuencia de comandos debe contener una rutina de conversión y un controlador onMessage.
2. En el service worker de la extensión, verifica chrome.storage para ver tus datos.
3. Si no se encuentran tus datos, llama a createDocument().
4. Después de que se resuelva la promesa devuelta, llama a sendMessage() para iniciar la rutina de conversión.
5. Dentro del controlador onMessage del documento fuera de pantalla, llama a la rutina de conversión.

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

Límites de almacenamiento y regulación

La API de Storage tiene limitaciones de uso:

• El almacenamiento de datos tiene costos de rendimiento, y la API incluye cuotas de almacenamiento. Planifica los datos que deseas almacenar para mantener espacio de almacenamiento.
• El almacenamiento puede tardar en completarse. Estructura 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.

Áreas de almacenamiento

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

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 solicitando el permiso "unlimitedStorage". Recomendamos usar storage.local para almacenar mayores cantidades de datos. De forma predeterminada, se expone a las secuencias de comandos de contenido, pero este comportamiento se puede cambiar llamando a chrome.storage.local.setAccessLevel().

Administrado

El almacenamiento administrado es de solo lectura para las extensiones instaladas por políticas. Los administradores del sistema lo administran con un esquema definido por el desarrollador y políticas empresariales. Las políticas son similares a las opciones, pero las configura un administrador del sistema, en lugar del usuario. Esto permite que la extensión se preconfigure para todos los usuarios de una organización.

De forma predeterminada, storage.managed se expone a las secuencias de comandos de contenido, pero este comportamiento se puede cambiar llamando a chrome.storage.managed.setAccessLevel(). 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.

Sesión

El almacenamiento de sesión mantiene los datos en la memoria mientras se carga una extensión. El almacenamiento se borra si la extensión se inhabilita, se vuelve a cargar, se actualiza y cuando se reinicia el navegador. De forma predeterminada, no se expone a las secuencias de comandos de contenido, pero este comportamiento se puede cambiar llamando a chrome.storage.session.setAccessLevel(). El límite de almacenamiento es de 10 MB (1 MB en Chrome 111 y versiones anteriores).

La interfazstorage.session es una de las varias que recomendamos para los service workers.

Sincronizar

Si el usuario habilita la sincronización, los datos se sincronizarán con todos los navegadores Chrome a los que haya accedido. Si está inhabilitado, se comporta como storage.local. Chrome almacena los datos de forma local cuando el navegador está sin conexión y reanuda la sincronización cuando vuelve a estar en línea. La limitación de la cuota es de aproximadamente 100 KB, es decir, 8 KB por elemento.

Te recomendamos que uses storage.sync para conservar la configuración del usuario en los navegadores sincronizados. Si trabajas con datos sensibles del usuario, usa storage.session en su lugar. De forma predeterminada, storage.sync se expone a las secuencias de comandos de contenido, pero este comportamiento se puede cambiar llamando a chrome.storage.sync.setAccessLevel().

Métodos y eventos

Todas las áreas de almacenamiento implementan la interfaz StorageArea.

get()

El método get() te permite leer una o más claves de un objeto StorageArea.

getBytesInUse()

El método getBytesInUse() te permite ver la cuota que usa un StorageArea.

getKeys()

El método getKeys() te permite obtener todas las claves almacenadas en un StorageArea.

remove()

El método remove() te permite quitar un elemento de un StorageArea.

set()

El método set() te permite establecer un elemento en un StorageArea.

setAccessLevel()

El método setAccessLevel() te permite controlar el acceso a un StorageArea.

clear()

El método clear() te permite borrar todos los datos de un objeto StorageArea.

onChanged

El evento onChanged te permite supervisar los cambios en un objeto StorageArea.

Casos de uso

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

Cómo responder 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 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 nueva configuración en storage.sync, y el trabajador de servicio usa storage.onChanged para aplicar el parámetro de 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);
  }
});

Precarga asíncrona desde el almacenamiento

Dado que los service workers no se ejecutan todo el tiempo, las extensiones de Manifest V3 a veces necesitan 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 complete el objeto global storageCache 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);
});

Herramientas para desarrolladores

Puedes ver y editar los datos almacenados con la API en Herramientas para desarrolladores. Para obtener más información, consulta la página Cómo ver y editar el almacenamiento de extensiones en la documentación de DevTools.

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