chrome.alarms

Descripción

Usa la API de chrome.alarms para programar que el código se ejecute de forma periódica o en un momento específico en el futuro.

Permisos

alarms

Manifest

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

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

Ejemplos

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

Establecer una alarma

En el siguiente ejemplo, se configura 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 configura el ícono de la barra de herramientas de acciones 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

  • name

    cadena

    Nombre de esta alarma

  • periodInMinutes

    número opcional

    Si no es nulo, la alarma es una alarma recurrente y se volverá a activar en periodInMinutes minutos.

  • scheduledTime

    número

    Hora a la que se programó la activación de esta alarma, expresada en milisegundos después de la época (p.ej., Date.now() + n). Por motivos de rendimiento, es posible que la alarma se haya retrasado más allá de este valor.

AlarmCreateInfo

Propiedades

  • delayInMinutes

    número opcional

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

  • periodInMinutes

    número opcional

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

  • cuándo

    número opcional

    Hora a la que se debe activar la alarma, expresada en milisegundos después de la época (p.ej., Date.now() + n).

Métodos

clear()

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

Borra la alarma con el nombre especificado.

Parámetros

  • name

    cadena opcional

    El nombre de la alarma que se borrará. La configuración predeterminada es la cadena vacía.

  • callback

    Función opcional

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

    (wasCleared: boolean)=>void

    • wasCleared

      boolean

Devuelve

  • Promise<boolean>

    Chrome 91 y versiones posteriores

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

Devuelve

  • Promise<boolean>

    Chrome 91 y versiones posteriores

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

create()

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

Crea una alarma. Cerca de los horarios especificados 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á con 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, configurar delayInMinutes o periodInMinutes en un valor inferior a 0.5 no se respetará y generará una advertencia. when se puede establecer en menos de 30 segundos después de "ahora" sin advertencia, pero no hará que la alarma se active durante al menos 30 segundos.

Para ayudarte a depurar tu app o extensión, una vez que la hayas cargado, no hay límite para la frecuencia con la que se puede activar la alarma.

Parámetros

  • name

    cadena opcional

    Nombre opcional para identificar esta alarma. La configuración predeterminada es la cadena 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 se establece periodInMinutes, la alarma se repetirá cada periodInMinutes minutos después del evento inicial. Si no se establecen when ni delayInMinutes para una alarma recurrente, se usa periodInMinutes como predeterminado para delayInMinutes.

  • callback

    Función opcional

    Chrome 111 y versiones posteriores

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

    ()=>void

Devuelve

  • Promise<void>

    Chrome 111 y versiones posteriores

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

get()

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

Recupera detalles sobre la alarma especificada.

Parámetros

  • name

    cadena opcional

    El nombre de la alarma que se escuchará. La configuración predeterminada es la cadena vacía.

  • callback

    Función opcional

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

    (alarm?: Alarm)=>void

Devuelve

  • Promesa<Alarm|undefined>

    Chrome 91 y versiones posteriores

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

getAll()

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

Obtiene una matriz de todas las alarmas.

Parámetros

  • callback

    Función opcional

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

    (alarms: Alarm[])=>void

Devuelve

  • Promesa<Alarm[]>

    Chrome 91 y versiones posteriores

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

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

    la función

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

    (alarm: Alarm)=>void