chrome.alarms

Descripción

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

Permisos

alarms

Manifiesto

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 responder a ella. Para probar esta API, instala el ejemplo de la API de Alarm desde el repositorio chrome-extension-samples.

Cómo 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
  });
});

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

  • persistAcrossSessions

    booleano

    Pendiente

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

  • scheduledTime

    número

    Hora en la que se programó la activación de esta alarma, en milisegundos después de 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 esto.

AlarmCreateInfo

Propiedades

  • delayInMinutes

    número opcional

    Duración 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 en las sesiones (reinicios del navegador). En Chrome, el valor predeterminado es true para que coincida con el comportamiento histórico, pero debes establecerlo de forma explícita para maximizar la compatibilidad en todos los navegadores.

  • cuándo

    número opcional

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

Métodos

clear()

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

Borra la alarma con el nombre determinado.

Parámetros

  • nombre

    string opcional

    El nombre de la alarma que se debe borrar. El valor predeterminado es la cadena vacía.

  • callback

    función opcional

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

    (wasCleared: boolean) => void

    • wasCleared

      booleano

Muestra

  • Promise<boolean>

    Chrome 91+

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

clearAll()

Promise 
chrome.alarms.clearAll(
  callback?: function,
): Promise<boolean>

Borra todas las alarmas.

Parámetros

  • callback

    función opcional

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

    (wasCleared: boolean) => void

    • wasCleared

      booleano

Muestra

  • Promise<boolean>

    Chrome 91+

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

create()

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

Crea una alarma. Cerca de la hora especificada por alarmInfo, se activa el evento onAlarm. Si hay otra alarma con el mismo nombre (o sin nombre si no se especifica ninguna), se cancelará y se reemplazará por esta alarma.

Para reducir la carga en la máquina del usuario, Chrome limita las alarmas a una vez cada 30 segundos como máximo, pero puede retrasarlas una cantidad arbitraria más. Es decir, si se establece delayInMinutes o periodInMinutes en menos de 0.5, no se respetará y se mostrará 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, cuando la cargas sin empaquetar, no hay límite para la frecuencia con la que se puede activar la alarma.

Parámetros

  • nombre

    string opcional

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

  • alarmInfo

    AlarmCreateInfo

    Indica cuándo se debe activar la alarma. La hora inicial se debe especificar 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 establece when ni delayInMinutes para una alarma repetitiva, periodInMinutes se usa como valor predeterminado para delayInMinutes.

  • callback

    función opcional

    Chrome 111+

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

    () => void

Muestra

  • Promise<void>

    Chrome 111+

    Promesa que se resuelve cuando se crea la alarma.

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

get()

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

Recupera los detalles de la alarma especificada.

Parámetros

  • nombre

    string opcional

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

  • callback

    función opcional

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

    (alarm?: Alarm) => void

Muestra

  • Promise<Alarm | undefined>

    Chrome 91+

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

getAll()

Promise 
chrome.alarms.getAll(
  callback?: function,
): Promise<Alarm[]>

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

  • Promise<Alarm[]>

    Chrome 91+

    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

    función

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

    (alarm: Alarm) => void