chrome.alarms

Descripción

Usa la API de chrome.alarms para programar la ejecución del código de forma periódica o en un momento específico 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 siguen sonando mientras el dispositivo está en suspensión. Sin embargo, una alarma no activará un dispositivo. Cuando el dispositivo se active, se activarán las alarmas perdidas. Las alarmas repetitivas se activarán como máximo una vez y, luego, se reprogramarán con el período especificado a partir del momento en que se active el dispositivo, sin tener en cuenta el tiempo que ya transcurrió desde que se configuró originalmente la alarma para que se ejecutara.

Persistencia

Puedes controlar la persistencia de una alarma en el momento de la creación con la marca persistAcrossSessions. Se puede establecer en true (persiste hasta que se actualiza la extensión) o false (se borra si se vuelve a cargar la extensión o se reinicia el navegador, y cada vez que se actualiza la extensión).

Otros navegadores y versiones anteriores de Chrome

Esta propiedad no se admite en otros navegadores (problema) ni en versiones de Chrome anteriores a la 150, en las que el comportamiento puede ser impredecible. Por lo tanto, lo mejor es asegurarse de que existan alarmas importantes cada vez que se inicie el service worker. Por ejemplo:

async function checkAlarmState() {
  const alarm = await chrome.alarms.get("my-alarm");

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

checkAlarmState();

Si la alarma se crea de forma dinámica según la acción del usuario, es posible que desees almacenar que se creó una alarma en otro lugar para saber que debes volver a crearla si es necesario.

Ejemplos

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

Cómo establecer una alarma

En el siguiente ejemplo, se configura una alarma en el service worker cuando se instala una nueva versión de la extensión:

service-worker.js:

chrome.runtime.onInstalled.addListener(async ({ reason }) => {
  // Create an alarm so we have something to look at in the demo
  await chrome.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1,
    persistAcrossSessions: true
  });
});

Cómo responder a una alarma

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

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 nulo, la alarma es repetitiva y se activará de nuevo en periodInMinutes minutos.

  • persistAcrossSessions

    booleano

    Pendiente

    Indica si la alarma debe persistir entre sesiones (reinicios del navegador).

  • scheduledTime

    número

    Fecha y hora en la que se programó la activación de esta alarma, en milisegundos transcurridos desde la época (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 de la cual se debe activar el evento onAlarm.

  • periodInMinutes

    número opcional

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

  • persistAcrossSessions

    booleano opcional

    Pendiente

    Indica si la alarma debe persistir entre sesiones (reinicios del navegador). En Chrome, este valor predeterminado es verdadero para que coincida con el comportamiento histórico, pero debes establecerlo de forma explícita para maximizar la compatibilidad entre navegadores.

  • cuándo

    número opcional

    Hora en la que debe activarse la alarma, en milisegundos transcurridos desde la época (p.ej., Date.now() + n).

Métodos

clear()

chrome.alarms.clear(
  name?: string,
): Promise<boolean>

Borra la alarma con el nombre determinado.

Parámetros

  • nombre

    cadena opcional

    Es el nombre de la alarma que se desactivará. El valor predeterminado es una cadena vacía.

Muestra

  • Promise<boolean>

    Chrome 91 y versiones posteriores

clearAll()

chrome.alarms.clearAll(): Promise<boolean>

Borra todas las alarmas.

Muestra

  • Promise<boolean>

    Chrome 91 y versiones posteriores

create()

chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
): Promise<void>

Crea una alarma. Cerca de la hora o las horas especificadas por alarmInfo, se activa el evento onAlarm. Si hay otra alarma con el mismo nombre (o sin nombre, si no se especificó ninguno), se cancelará y se reemplazará por esta alarma.

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

Para ayudarte a depurar tu app o extensión, cuando la hayas cargado sin empaquetar, no habrá límite para la frecuencia con la que se puede activar la alarma.

Parámetros

  • nombre

    cadena opcional

    Nombre opcional para identificar esta alarma. El valor predeterminado es una cadena vacía.

  • alarmInfo

    AlarmCreateInfo

    Describe cuándo debe sonar la alarma. La hora inicial se debe especificar con when o delayInMinutes (pero no con ambos). Si se configura periodInMinutes, la alarma se repetirá cada periodInMinutes minutos después del evento inicial. Si no se configuran when ni delayInMinutes para una alarma recurrente, se usa periodInMinutes como valor predeterminado para delayInMinutes.

Muestra

  • Promise<void>

    Chrome 111 y versiones posteriores

    Es una promesa que se resuelve cuando se crea la alarma.

get()

chrome.alarms.get(
  name?: string,
): Promise<Alarm | undefined>

Recupera detalles sobre la alarma especificada.

Parámetros

  • nombre

    cadena opcional

    Nombre de la alarma que se obtendrá. El valor predeterminado es una cadena vacía.

Muestra

  • Promise<Alarm | undefined>

    Chrome 91 y versiones posteriores

getAll()

chrome.alarms.getAll(): Promise<Alarm[]>

Obtiene un array de todas las alarmas.

Muestra

  • Promise<Alarm[]>

    Chrome 91 y versiones posteriores

Eventos

onAlarm

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

Se activa cuando transcurre una alarma. Es útil para las páginas de eventos.

Parámetros

  • callback

    función

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

    (alarm: Alarm) => void