Description
Utilisez l'API chrome.alarms
pour planifier l'exécution du code régulièrement ou à une heure spécifiée dans le futur.
Autorisations
alarms
Manifest
Pour utiliser l'API chrome.alarms
, déclarez l'autorisation "alarms"
dans le fichier manifeste:
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
Exemples
Les exemples suivants montrent comment utiliser une alarme et y répondre. Pour essayer cette API, installez l'exemple d'API Alarm à partir du dépôt chrome-extension-samples.
Régler une alarme
L'exemple suivant définit une alarme dans le service worker lorsque l'extension est installée:
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
});
});
Répondre à une alarme
L'exemple suivant définit l'icône des actions de la barre d'outils en fonction du nom de l'alarme qui s'est déclenchée.
service-worker.js :
chrome.alarms.onAlarm.addListener((alarm) => {
chrome.action.setIcon({
path: getIconPath(alarm.name),
});
});
Types
Alarm
Propriétés
-
name
chaîne
Nom de cette alarme.
-
periodInMinutes
numéro facultatif
Si la valeur n'est pas nulle, l'alarme est récurrente et se déclenche de nouveau dans
periodInMinutes
minutes. -
scheduledTime
Nombre
Heure à laquelle cette alarme était programmée pour se déclencher, en millisecondes après l'epoch (par exemple,
Date.now() + n
). Pour des raisons de performances, l'alarme peut avoir été retardée d'une valeur arbitraire au-delà de ce délai.
AlarmCreateInfo
Propriétés
-
delayInMinutes
numéro facultatif
Durée, en minutes, au terme de laquelle l'événement
onAlarm
doit se déclencher. -
periodInMinutes
numéro facultatif
S'il est défini, l'événement onAlarm doit se déclencher toutes les
periodInMinutes
minutes après l'événement initial spécifié parwhen
oudelayInMinutes
. Si cette règle n'est pas configurée, l'alarme ne se déclenche qu'une seule fois. -
when
numéro facultatif
Heure à laquelle l'alarme doit se déclencher, en millisecondes après l'epoch (par exemple,
Date.now() + n
).
Méthodes
clear()
chrome.alarms.clear(
name?: string,
callback?: function,
)
Efface l'alarme portant le nom indiqué.
Paramètres
-
name
string facultatif
Nom de l'alarme à effacer. La valeur par défaut est la chaîne vide.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(wasCleared: boolean) => void
-
wasCleared
boolean
-
Renvoie
-
Promise<boolean>
Chrome 91 et versions ultérieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
Efface toutes les alarmes.
Paramètres
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(wasCleared: boolean) => void
-
wasCleared
boolean
-
Renvoie
-
Promise<boolean>
Chrome 91 et versions ultérieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
)
Crée une alarme. À peu près au(x) moment(s) spécifié(s) par alarmInfo
, l'événement onAlarm
est déclenché. S'il existe une autre alarme portant le même nom (ou si aucun nom n'est spécifié), elle est annulée et remplacée par cette alarme.
Afin de réduire la charge sur l'ordinateur de l'utilisateur, Chrome limite les alarmes à une fois toutes les 30 secondes au maximum, mais peut les retarder d'une manière arbitraire. Autrement dit, si vous définissez delayInMinutes
ou periodInMinutes
sur une valeur inférieure à 0.5
, cela ne sera pas respecté et entraînera un avertissement. when
peut être réglé sur moins de 30 secondes après "now" (maintenant) sans avertissement, mais ne déclenchera pas l'alarme pendant au moins 30 secondes.
Pour vous aider à déboguer votre application ou votre extension, une fois que vous l'avez chargée non empaquetée, il n'y a aucune limite à la fréquence de déclenchement de l'alarme.
Paramètres
-
name
string facultatif
Nom facultatif permettant d'identifier cette alarme. La valeur par défaut est la chaîne vide.
-
alarmInfo
Décrit à quel moment l'alarme doit se déclencher. L'heure initiale doit être spécifiée avec
when
oudelayInMinutes
(mais pas les deux). SiperiodInMinutes
est défini, l'alarme se répètera toutes lesperiodInMinutes
minutes après l'événement initial. Si niwhen
, nidelayInMinutes
n'est défini pour une alarme récurrente,periodInMinutes
est utilisé par défaut pourdelayInMinutes
. -
rappel
fonction facultative
Chrome 111 et versions ultérieuresLe paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 111 et versions ultérieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
Récupère les détails de l'alarme spécifiée.
Paramètres
Renvoie
-
Promise<Alarm | undefined>
Chrome 91 et versions ultérieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
getAll()
chrome.alarms.getAll(
callback?: function,
)
Récupère un tableau de toutes les alarmes.
Paramètres
Renvoie
-
Promesse<Alarme[]>
Chrome 91 et versions ultérieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.