chrome.alarms

Descripción

Usa la API de chrome.alarms para programar que el código se ejecute de forma periódica o a una hora específica en el futuro.

Permisos

alarms

Para usar la API de chrome.alarms, declara el permiso "alarms" en el manifiesto:

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

Conceptos y uso

Para garantizar un comportamiento confiable, es útil comprender cómo se comporta la API.

Suspensión del dispositivo

Las alarmas seguirán sonando mientras el dispositivo esté suspendido. Sin embargo, una alarma no activar un dispositivo. Cuando el dispositivo se active, se activarán las alarmas perdidas. Las alarmas repetidas se activarán como máximo una vez y luego se reprogramarán con el período especificado a partir de la fecha en que se activa el dispositivo, sin tener en cuenta cualquier tiempo que ya haya transcurrido desde que la alarma se configuró originalmente para ejecutarse.

Persistencia

Por lo general, las alarmas persisten hasta que se actualiza una extensión. Sin embargo, esto no está garantizado, y las alarmas puede borrarse cuando se reinicia el navegador. Por lo tanto, considera establecer un valor en el almacenamiento cuando se cree una alarma, y asegúrate de que exista cada vez que se inicie el service worker. Por ejemplo:

const STORAGE_KEY = "user-preference-alarm-enabled";

async function checkAlarmState() {
  const { alarmEnabled } = await chrome.storage.get(STORAGE_KEY);

  if (alarmEnabled) {
    const alarm = await chrome.alarms.get("my-alarm");

    if (!alarm) {
      await chrome.alarms.create({ periodInMinutes: 1 });
    }
  }
}

checkAlarmState();

Ejemplos

En los siguientes ejemplos, se muestra cómo usar y responder una alarma. Para probar esta API, instala el ejemplo de la API de Alarm desde chrome-extension-samples en un repositorio de confianza.

Establecer una alarma

En el siguiente ejemplo, se establece una alarma en el service worker cuando se instala la extensión:

service-worker.js:

chrome.runtime.onInstalled.addListener(async ({ reason }) => {
  if (reason !== 'install') {
    return;
  }

  // Create an alarm so we have something to look at in the demo
  await chrome.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1
  });
});

Cómo responder a una alarma

En el siguiente ejemplo, se establece el ícono de la barra de herramientas de acciones según el nombre de la alarma que se activó.

service-worker.js:

chrome.alarms.onAlarm.addListener((alarm) => {
  chrome.action.setIcon({
    path: getIconPath(alarm.name),
  });
});

Tipos

Alarm

Propiedades

  • nombre

    string

    Nombre de esta alarma.

  • periodInMinutes

    número opcional

    Si no es nula, es una alarma recurrente y se activará de nuevo en periodInMinutes minutos.

  • scheduledTime

    número

    Hora a la que se programó esta alarma para que se active, en milisegundos transcurridos el ciclo de entrenamiento (p.ej., Date.now() + n). Por motivos de rendimiento, es posible que la alarma se haya retrasado una cantidad arbitraria más allá de este valor.

AlarmCreateInfo

Propiedades

  • delayInMinutes

    número opcional

    Es la cantidad de tiempo, en minutos, después del cual se debe activar el evento onAlarm.

  • periodInMinutes

    número opcional

    Si se establece, el evento onAlarm debe activarse cada periodInMinutes minutos después del evento inicial especificado por when o delayInMinutes. Si no se establece, la alarma solo se activará una vez.

  • cuándo

    número opcional

    Hora en la que debe activarse la alarma, expresada en milisegundos transcurridos el ciclo de entrenamiento (p.ej., Date.now() + n).

Métodos

clear()

Promesa 
chrome.alarms.clear(
  name?: string,
  callback?: function,
)

Borra la alarma con el nombre dado.

Parámetros

  • nombre

    string opcional

    El nombre de la alarma que se borrará. El valor predeterminado es la string vacía.

  • callback

    función opcional

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

    (wasCleared: boolean) => void

    • wasCleared

      boolean

Muestra

  • Promise<boolean>

    Chrome 91 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

clearAll()

Promesa 
chrome.alarms.clearAll(
  callback?: function,
)

Borra todas las alarmas.

Parámetros

  • callback

    función opcional

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

    (wasCleared: boolean) => void

    • wasCleared

      boolean

Muestra

  • Promise<boolean>

    Chrome 91 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

create()

Promesa 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

Crea una alarma. Cerca del tiempo especificado por alarmInfo, se activa el evento onAlarm. Si hay otra alarma con el mismo nombre (o sin nombre si no se especifica ninguno), se cancelará y se reemplazará por esta alarma.

Para reducir la carga en la máquina del usuario, Chrome limita las alarmas a, como máximo, una vez cada 30 segundos, pero puede retrasarlas una cantidad arbitraria más. Es decir, si estableces delayInMinutes o periodInMinutes en un valor menor que 0.5, no se respetará y generará una advertencia. when se puede establecer en menos de 30 segundos después de "ahora" sin previo aviso, pero no hará que la alarma se active durante al menos 30 segundos.

Para ayudarte a depurar tu app o extensión, cuando la hayas cargado sin empaquetar, no hay límite en la frecuencia con la que puede activarse la alarma.

Parámetros

  • nombre

    string opcional

    Nombre opcional para identificar esta alarma. El valor predeterminado es la string vacía.

  • alarmInfo

    AlarmCreateInfo

    Describe cuándo debe activarse la alarma. La hora inicial debe especificarse con when o delayInMinutes (pero no con ambos). Si estableces periodInMinutes, la alarma se repetirá cada periodInMinutes minutos después del evento inicial. Si no se estableció when ni delayInMinutes para una alarma recurrente, se usará periodInMinutes como valor predeterminado para delayInMinutes.

  • callback

    función opcional

    Chrome 111 y versiones posteriores

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

    () => void

Muestra

  • Promesa<void>

    Chrome 111 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

get()

Promesa 
chrome.alarms.get(
  name?: string,
  callback?: function,
)

Recupera los detalles sobre la alarma especificada.

Parámetros

  • nombre

    string opcional

    El nombre de la alarma que se debe obtener. El valor predeterminado es la string vacía.

  • callback

    función opcional

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

    (alarm?: Alarm) => void

Muestra

  • Promise&lt;Alarm | indefinido>

    Chrome 91 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getAll()

Promesa 
chrome.alarms.getAll(
  callback?: function,
)

Obtiene un array de todas las alarmas.

Parámetros

  • callback

    función opcional

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

    (alarms: Alarm[]) => void

Muestra

  • Promesa<Alarma[]>

    Chrome 91 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

Eventos

onAlarm

chrome.alarms.onAlarm.addListener(
  callback: function,
)

Se activa cuando ha transcurrido una alarma. Útil para páginas de eventos.

Parámetros

  • callback

    función

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

    (alarm: Alarm) => void