chrome.alarms

refresh date: 2026-09-25 robots: noindex

Description

Utilisez l'API chrome.alarms pour planifier l'exécution de code à intervalles réguliers ou à une heure précise dans le futur.

Autorisations

alarms

Fichier manifeste

Pour utiliser l'API chrome.alarms, déclarez l'autorisation "alarms" dans le 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 de la barre d'outils d'action 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

  • nom

    chaîne

    Nom de cette alarme.

  • periodInMinutes

    number facultatif

    Si la valeur n'est pas nulle, l'alarme est récurrente et se déclenchera à nouveau dans periodInMinutes minutes.

  • persistAcrossSessions

    booléen

    Chrome 150 et versions ultérieures

    Indique si l'alarme doit persister d'une session à l'autre (redémarrage du navigateur).

  • scheduledTime

    nombre

    Heure à laquelle cette alarme devait se déclencher, en millisecondes depuis l'époque (par exemple, Date.now() + n). Pour des raisons de performances, l'alarme peut avoir été retardée d'une durée arbitraire.

AlarmCreateInfo

Propriétés

  • delayInMinutes

    number facultatif

    Durée en minutes après laquelle l'événement onAlarm doit se déclencher.

  • nom

    chaîne facultatif

    Chrome 152 et versions ultérieures

    Nom de cette alarme.

  • periodInMinutes

    number facultatif

    Si elle est définie, l'événement onAlarm doit se déclencher toutes les periodInMinutes minutes après l'événement initial spécifié par when ou delayInMinutes. Si elle n'est pas définie, l'alarme ne se déclenchera qu'une seule fois.

  • persistAcrossSessions

    booléen facultatif

    Chrome 150 et versions ultérieures

    Indique si l'alarme doit persister d'une session à l'autre (redémarrage du navigateur). Dans Chrome, la valeur par défaut est "true" pour correspondre au comportement historique, mais vous devez la définir explicitement pour maximiser la compatibilité entre les navigateurs.

  • when

    number facultatif

    Heure à laquelle l'alarme doit se déclencher, en millisecondes depuis l'epoch (par exemple, Date.now() + n).

Méthodes

clear()

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

Efface l'alarme portant le nom indiqué.

Paramètres

  • nom

    chaîne facultatif

    Nom de l'alarme à désactiver. La valeur par défaut est une chaîne vide.

  • callback

    function facultatif

    Le paramètre callback se présente comme suit : 

    (wasCleared: boolean) => void

    • wasCleared

      booléen

Renvoie

  • Promise<boolean>

    Chrome 91 et versions ultérieures

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

clearAll()

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

Efface toutes les alarmes.

Paramètres

  • callback

    function facultatif

    Le paramètre callback se présente comme suit : 

    (wasCleared: boolean) => void

    • wasCleared

      booléen

Renvoie

  • Promise<boolean>

    Chrome 91 et versions ultérieures

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

create()

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

Crée une alarme. L'événement onAlarm est déclenché à l'heure ou aux heures spécifiées par alarmInfo. S'il existe une autre alarme portant le même nom (ou sans nom si aucun n'est spécifié), elle sera annulée et remplacée par celle-ci.

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 durée arbitraire. En d'autres termes, si vous définissez delayInMinutes ou periodInMinutes sur une valeur inférieure à 0.5, cette valeur ne sera pas prise en compte et un avertissement s'affichera. when peut être défini sur une durée inférieure à 30 secondes après "maintenant" sans avertissement, mais l'alarme ne se déclenchera pas avant au moins 30 secondes.

Pour vous aider à déboguer votre application ou extension, lorsque vous l'avez chargée non empaquetée, la fréquence de déclenchement de l'alarme n'est pas limitée.

Paramètres

  • nom

    chaîne facultatif

    Nom facultatif permettant d'identifier cette alarme. La valeur par défaut est une chaîne vide.

  • alarmInfo

    AlarmCreateInfo

    Décrit le moment où l'alarme doit se déclencher. L'heure initiale doit être spécifiée par when ou delayInMinutes (mais pas les deux). Si periodInMinutes est défini, l'alarme se répète toutes les periodInMinutes minutes après l'événement initial. Si ni when ni delayInMinutes ne sont définis pour une alarme récurrente, periodInMinutes est utilisé comme valeur par défaut pour delayInMinutes.

  • callback

    function facultatif

    Chrome 111 et versions ultérieures

    Le paramètre callback se présente comme suit : 

    () => void

Renvoie

  • Promise<void>

    Chrome 111 et versions ultérieures

    Promesse qui se résout lorsque l'alarme a été créée.

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

get()

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

Récupère les détails de l'alarme spécifiée.

Paramètres

  • nom

    chaîne facultatif

    Nom de l'alarme à obtenir. La valeur par défaut est une chaîne vide.

  • callback

    function facultatif

    Le paramètre callback se présente comme suit : 

    (alarm?: Alarm) => void

Renvoie

  • Promise<Alarm | undefined>

    Chrome 91 et versions ultérieures

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getAll()

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

Récupère un tableau de toutes les alarmes.

Paramètres

  • callback

    function facultatif

    Le paramètre callback se présente comme suit : 

    (alarms: Alarm[]) => void

Renvoie

  • Promise<Alarm[]>

    Chrome 91 et versions ultérieures

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

Événements

onAlarm

chrome.alarms.onAlarm.addListener(
  callback: function,
)

Déclenché lorsqu'une alarme a sonné. Utile pour les pages d'événements.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (alarm: Alarm) => void