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
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 ejecutándose mientras el dispositivo está suspendido. Sin embargo, una alarma no activará un dispositivo. Cuando se active el dispositivo, se activarán las alarmas omitidas. Las alarmas recurrentes se activarán una vez como máximo 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 transcurrido desde que se configuró originalmente la alarma.
Persistencia
Por lo general, las alarmas persisten hasta que se actualiza una extensión. Sin embargo, esto no está garantizado y es posible que se borren las alarmas cuando se reinicie el navegador. Por lo tanto, considera establecer un valor en almacenamiento cuando se cree una alarma y, luego, 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 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 porwhen
odelayInMinutes
. 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()
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 posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
clearAll()
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 posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
create()
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
Describe cuándo debe activarse la alarma. La hora inicial debe especificarse con
when
odelayInMinutes
(pero no con ambos). Si se estableceperiodInMinutes
, la alarma se repetirá cadaperiodInMinutes
minutos después del evento inicial. Si no se establecenwhen
nidelayInMinutes
para una alarma recurrente, se usaperiodInMinutes
como predeterminado paradelayInMinutes
. -
callback
Función opcional
Chrome 111 y versiones posterioresEl parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Chrome 111 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
Recupera detalles sobre la alarma especificada.
Parámetros
Devuelve
-
Promise<Alarm | undefined>
Chrome 91 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
getAll()
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
-
Alarmas
-
Devuelve
-
Promesa<Alarm[]>
Chrome 91 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.