chrome.storage

Descripción

Usa la API de chrome.storage para almacenar datos del usuario, recuperarlos y hacerles un seguimiento.

Permisos

storage

Descripción general

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. Las siguientes son algunas funciones clave:

  • Todos los contextos de extensiones, incluidos el service worker de extensiones y las secuencias de comandos de contenido, tienen acceso a la API de Storage.
  • Los valores serializables de JSON se almacenan como propiedades del objeto.
  • 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 se mantiene incluso cuando se usa dividir el modo incógnito.
  • Incluye un área de almacenamiento administrado exclusiva de solo lectura para las políticas empresariales.

Aunque las extensiones pueden usar la interfaz [Storage][mdn-storage] (accesible desde window.localStorage) en algunos contextos (páginas emergentes y HTML), no se recomienda por los siguientes motivos:

  • El service worker de la extensión no puede acceder a Storage.
  • Las secuencias de comandos de contenido comparten el almacenamiento con la página de host.
  • Los datos guardados con la interfaz de 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. Crea un documento fuera de pantalla con una rutina de conversión y un controlador [onMessage][on-message].
  2. Agrega una rutina de conversión a un documento fuera de pantalla.
  3. En el service worker de extensión, busca tus datos en chrome.storage.
  4. Si no se encuentran tus datos, [create][create-offscreen] en un documento fuera de pantalla y llama a [sendMessage()][send-message] para iniciar la rutina de conversiones.
  5. 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][storage-and-cookies].

Áreas de almacenamiento

La API de Storage se divide en los siguientes cuatro buckets ("áreas de almacenamiento"):

storage.local
Los datos se almacenan de forma local, que se borran cuando se quita la extensión. El límite de cuota es de aproximadamente 10 MB, pero se puede aumentar si solicitas el permiso "unlimitedStorage". Considera usarlo para almacenar grandes cantidades de datos.
storage.sync
Si la sincronización está habilitada, los datos se sincronizan con cualquier navegador Chrome al que el usuario haya accedido. Si está inhabilitada, se comporta como storage.local. Chrome almacena los datos localmente cuando el navegador no tiene 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, 8 KB por elemento. Te recomendamos que la uses para preservar la configuración de los usuarios en todos los navegadores sincronizados.
storage.session
Retiene datos en la memoria durante una sesión del navegador. De forma predeterminada, no se expone a secuencias de comandos de contenido, pero este comportamiento se puede cambiar si se configura chrome.storage.session.setAccessLevel(). El límite de cuota es de aproximadamente 10 MB. Considera usarlo para almacenar variables globales en distintas ejecuciones de service worker.
storage.managed
Los administradores pueden usar un esquema y políticas empresariales para establecer la configuración de una extensión complementaria en un entorno administrado. Esta área de almacenamiento es de solo lectura.

Manifest

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

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

Uso

En los siguientes ejemplos, se muestran las áreas de almacenamiento local, sync y 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 obtener más información sobre el área de almacenamiento de managed, consulta el Manifiesto de las áreas de almacenamiento.

Límites de almacenamiento y regulación

No pienses en agregar a la API de Storage como si fuera un camión grande. Piensa en agregar al almacenamiento como poner algo en una canalización. Es posible que la tubería ya tenga material, e incluso puede estar rellenada. Siempre debes asumir que hay una demora entre el momento en que agregas el almacenamiento y el momento en que se registra.

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

Casos de uso

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

Respuesta síncrona a las actualizaciones de almacenamiento

Para realizar un seguimiento de los cambios realizados en el almacenamiento, puedes agregar un objeto de escucha a su evento onChanged. Cuando se produce algún cambio 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 service worker utiliza 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);
  }
});

Precarga asíncrona desde el almacenamiento

Dado que los service workers no siempre se ejecutan, 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 propague el 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);
});

Ejemplos de extensiones

Para ver otras demostraciones de la API de Storage, explora cualquiera de los siguientes ejemplos:

Tipos

AccessLevel

Chrome 102 y versiones posteriores

El nivel de acceso del área de almacenamiento.

Enum

"TRUSTED_CONTEXTS"
Especifica los contextos que se originan en la propia extensión.

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
Especifica contextos que se originan fuera de la extensión.

StorageArea

Propiedades

  • onChanged

    Evento<functionvoidvoid>

    Chrome 73 y versiones posteriores

    Se activa cuando cambian uno o más elementos.

    La función onChanged.addListener se ve de la siguiente manera: 

    (callback: function)=> {...}

    • callback

      la 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

    • resultados

      Promise<void>

      Chrome 88 y versiones posteriores

      Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones 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

      string|string[]|object optional

      Una clave única para obtener, una lista de claves para obtener o un diccionario que especifica valores predeterminados (consulta la descripción del objeto). Una lista o un objeto vacíos devolverá 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

      • items

        objeto

        Objeto con elementos en sus asignaciones de pares clave-valor.

    • resultados

      Promise<object>

      Chrome 88 y versiones posteriores

      Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones 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

      string|string[] optional

      Una sola clave o 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

        Cantidad de espacio que se usa en el almacenamiento, en bytes.

    • resultados

      Promesa<number>

      Chrome 88 y versiones posteriores

      Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

  • quitarlo

    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 para los elementos que se quitarán.

    • callback

      Función opcional

      El parámetro callback se ve de la siguiente manera: 

      ()=>void

    • resultados

      Promise<void>

      Chrome 88 y versiones posteriores

      Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

  • set

    void

    Promesa

    Configura varios elementos.

    La función set se ve de la siguiente manera: 

    (items: object,callback?: function)=> {...}

    • items

      objeto

      Es un objeto que le da a cada par clave-valor para actualizar el almacenamiento. No se verán afectados los demás pares clave-valor almacenados.

      Los valores primitivos, como los números, se serializarán como se espera. Por lo general, los valores con "object" y "function" de typeof se serializan en {}, a excepción de Array (se serializa según lo esperado), Date y Regex (se serializan con su representación String).

    • callback

      Función opcional

      El parámetro callback se ve de la siguiente manera: 

      ()=>void

    • resultados

      Promise<void>

      Chrome 88 y versiones posteriores

      Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones 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 será solo para contextos de confianza.

    La función setAccessLevel se ve de la siguiente manera: 

    (accessOptions: object,callback?: function)=> {...}

    • accessOptions

      objeto

      • accessLevel

        AccessLevel

        El nivel de acceso del área de almacenamiento.

    • callback

      Función opcional

      El parámetro callback se ve de la siguiente manera: 

      ()=>void

    • resultados

      Promise<void>

      Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

StorageChange

Propiedades

  • newValue

    cualquier opcional

    Es el valor nuevo del elemento, si hay uno nuevo.

  • oldValue

    cualquier opcional

    El valor anterior del artículo, si había uno anterior.

Propiedades

local

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

Tipo

StorageArea&object

Propiedades

  • QUOTA_BYTES

    10485760

    La cantidad máxima (en bytes) de datos que se pueden almacenar en el almacenamiento local, medida por la 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 provocan que se supere este límite fallan de inmediato y configuran runtime.lastError cuando se usa una devolución de llamada, o bien una promesa rechazada si se usa async/await.

managed

Los elementos del área de almacenamiento de managed se establecen mediante una política empresarial configurada por el administrador del dominio, que son de solo lectura para la extensión. Si intentas modificar el espacio de nombres, se produce un error. Si quieres obtener información para 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 conservarán en el disco.

Tipo

StorageArea&object

Propiedades

  • QUOTA_BYTES

    10485760

    La cantidad máxima (en bytes) de datos que se pueden almacenar en la memoria, según la medición del uso de memoria asignado de forma dinámica de cada valor y clave. Las actualizaciones que provocan que se supere este límite fallan de inmediato y se establece runtime.lastError cuando se usa una devolución de llamada o cuando se rechaza una promesa.

sync

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

Tipo

StorageArea&object

Propiedades

  • MAX_ITEMS

    512

    La cantidad máxima de elementos que se pueden almacenar en el almacenamiento sincronizado. Las actualizaciones que provocan que se supere este límite fallarán de inmediato y se 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 operaciones de escritura sostenidas.

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1,800

    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 al límite más alto de escrituras por minuto a corto plazo.

    Las actualizaciones que provocan que se supere este límite fallan de inmediato y se establece runtime.lastError cuando se usa una devolución de llamada o cuando se rechaza una promesa.

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

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

    Las actualizaciones que provocan que se supere este límite fallan de inmediato y se establece runtime.lastError cuando se usa una devolución de llamada o cuando se rechaza una promesa.

  • QUOTA_BYTES

    102400

    La cantidad total máxima (en bytes) de datos que se pueden almacenar en el almacenamiento sincronizado, medida por la string JSON de cada valor más la longitud de cada clave. Las actualizaciones que provocan que se supere este límite fallan de inmediato y se establece runtime.lastError cuando se usa una devolución de llamada o cuando se rechaza una promesa.

  • QUOTA_BYTES_PER_ITEM

    8192

    El tamaño máximo (en bytes) de cada elemento individual en el almacenamiento sincronizado, medido por la clasificación en string JSON de su valor más su longitud de clave. Las actualizaciones que contengan elementos superiores a este límite fallarán de inmediato y se 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 cambian uno o más elementos.

Parámetros

  • callback

    la función

    El parámetro callback se ve de la siguiente manera: 

    (changes: object,areaName: string)=>void

    • Cambios

      objeto

    • areaName

      cadena