Descripción
Usa la API de chrome.alarms
para programar que el código se ejecute de forma periódica o a una hora específica 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 y responder una alarma. Para probar esta API, instala el ejemplo de la API de Alarm desde chrome-extension-samples en un repositorio de confianza.
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
});
});
Cómo responder a una alarma
En el siguiente ejemplo, se establece el ícono de la barra de herramientas de acciones 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 nula, es una alarma recurrente y se activará de nuevo en
periodInMinutes
minutos. -
scheduledTime
número
Hora a la que se programó esta alarma para que se active, en milisegundos transcurridos el ciclo de entrenamiento (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 del cual se debe activar el evento
onAlarm
. -
periodInMinutes
número opcional
Si se establece, el evento onAlarm debe activarse cada
periodInMinutes
minutos después del evento inicial especificado porwhen
odelayInMinutes
. Si no se establece, la alarma solo se activará una vez. -
cuándo
número opcional
Hora en la que debe activarse la alarma, expresada en milisegundos transcurridos el ciclo de entrenamiento (p.ej.,
Date.now() + n
).
Métodos
clear()
chrome.alarms.clear(
name?: string,
callback?: function,
)
Borra la alarma con el nombre dado.
Parámetros
-
nombre
string opcional
El nombre de la alarma que se borrará. El valor predeterminado es la string vacía.
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:(wasCleared: boolean) => void
-
wasCleared
boolean
-
Muestra
-
Promise<boolean>
Chrome 91 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones 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
-
Muestra
-
Promise<boolean>
Chrome 91 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
)
Crea una alarma. Cerca del tiempo especificado 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á por 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, si estableces delayInMinutes
o periodInMinutes
en un valor menor que 0.5
, no se respetará y generará una advertencia. when
se puede establecer en menos de 30 segundos después de "ahora" sin previo aviso, pero no hará que la alarma se active durante al menos 30 segundos.
Para ayudarte a depurar tu app o extensión, cuando la hayas cargado sin empaquetar, no hay límite en la frecuencia con la que puede activarse la alarma.
Parámetros
-
nombre
string opcional
Nombre opcional para identificar esta alarma. El valor predeterminado es la string vacía.
-
alarmInfo
Describe cuándo debe activarse la alarma. La hora inicial debe especificarse con
when
odelayInMinutes
(pero no con ambos). Si establecesperiodInMinutes
, la alarma se repetirá cadaperiodInMinutes
minutos después del evento inicial. Si no se estableciówhen
nidelayInMinutes
para una alarma recurrente, se usaráperiodInMinutes
como valor predeterminado paradelayInMinutes
. -
callback
función opcional
Chrome 111 y versiones posterioresEl parámetro
callback
se ve de la siguiente manera:() => void
Muestra
-
Promesa<void>
Chrome 111 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
Recupera los detalles sobre la alarma especificada.
Parámetros
Muestra
-
Promise<Alarm | indefinido>
Chrome 91 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
getAll()
chrome.alarms.getAll(
callback?: function,
)
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
-
Alarmas
-
Muestra
-
Promesa<Alarma[]>
Chrome 91 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.