Descripción
Usa la API de chrome.alarms para programar el código de modo que se ejecute de forma periódica o en un momento específico en el futuro.
Permisos
alarmsManifiesto
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 de chrome-extension-samples.
Cómo 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 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 recurrente y se activará de nuevo en
periodInMinutesminutos. -
scheduledTime
número
Hora a 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
periodInMinutesminutos después del evento inicial especificado porwhenodelayInMinutes. Si no se configura, la alarma solo se activará una vez. -
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,
callback?: function,
): Promise<boolean>
Borra la alarma con el nombre determinado.
Parámetros
-
nombre
cadena opcional
Es el nombre de la alarma que se borrará. El valor predeterminado es una cadena vacía.
-
callback
función opcional
El parámetro
callbackse ve de la siguiente manera:(wasCleared: boolean) => void
-
wasCleared
booleano
-
Muestra
-
Promise<boolean>
Chrome 91 y versiones posterioresLas promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.
clearAll()
chrome.alarms.clearAll(
callback?: function,
): Promise<boolean>
Borra todas las alarmas.
Parámetros
-
callback
función opcional
El parámetro
callbackse ve de la siguiente manera:(wasCleared: boolean) => void
-
wasCleared
booleano
-
Muestra
-
Promise<boolean>
Chrome 91 y versiones posterioresLas promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
): 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 no activará la alarma durante al menos 30 segundos.
Para ayudarte a depurar tu app o extensión, cuando la cargues sin empaquetar, no habrá límite en 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
Describe cuándo debe sonar la alarma. La hora inicial se debe especificar con
whenodelayInMinutes(pero no con ambos). Si se configuraperiodInMinutes, la alarma se repetirá cadaperiodInMinutesminutos después del evento inicial. Si no se configuranwhennidelayInMinutespara una alarma recurrente, se usaperiodInMinutescomo valor predeterminado paradelayInMinutes. -
callback
función opcional
Chrome 111 y versiones posterioresEl parámetro
callbackse ve de la siguiente manera:() => void
Muestra
-
Promise<void>
Chrome 111 y versiones posterioresLas promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.
get()
chrome.alarms.get(
name?: string,
callback?: function,
): Promise<Alarm | undefined>
Recupera detalles sobre la alarma especificada.
Parámetros
Muestra
-
Promise<Alarm | undefined>
Chrome 91 y versiones posterioresLas promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.
getAll()
chrome.alarms.getAll(
callback?: function,
): Promise<Alarm[]>
Obtiene un array de todas las alarmas.
Parámetros
Muestra
-
Promise<Alarm[]>
Chrome 91 y versiones posterioresLas promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.