chrome.alarms

Description

Utilisez l'API chrome.alarms pour planifier l'exécution de code de manière périodique ou à une heure spécifiée.

Autorisations

alarms

Pour utiliser l'API chrome.alarms, déclarez l'autorisation "alarms" dans le fichier manifeste :

{
  "name": "My extension",
  ...
  "permissions": [
    "alarms"
  ],
  ...
}

Concepts et utilisation

Pour garantir un comportement fiable, il est utile de comprendre le fonctionnement de l'API.

Veille de l'appareil

Les alarmes continuent de fonctionner lorsque l'appareil est en veille. Toutefois, une alarme ne réveillera pas un appareil. Lorsque l'appareil se réveille, toutes les alarmes manquées se déclenchent. Les alarmes répétées se déclenchent au maximum une fois, puis sont reprogrammées à l'aide de la période spécifiée à partir du moment où l'appareil se réveille, sans tenir compte du temps déjà écoulé depuis le déclenchement initial de l'alarme.

Persistance

Vous pouvez contrôler la persistance d'une alarme au moment de sa création à l'aide de l'indicateur persistAcrossSessions. Vous pouvez définir la valeur sur true (persiste jusqu'à la mise à jour de l'extension) ou false (effacée si l'extension est rechargée ou si le navigateur redémarre, et chaque fois que l'extension est mise à jour).

Autres navigateurs et versions antérieures de Chrome

Cette propriété n'est pas compatible avec d'autres navigateurs (problème) ni avec les versions de Chrome antérieures à Chrome 150, où le comportement peut être imprévisible. Par conséquent, il est préférable de s'assurer que les alarmes importantes existent chaque fois que votre service worker démarre. Exemple :

async function checkAlarmState() {
  const alarm = await chrome.alarms.get("my-alarm");

  if (!alarm) {
    await chrome.alarms.create("my-alarm", { periodInMinutes: 1 });
  }
}

checkAlarmState();

Si votre alarme est créée de manière dynamique en fonction de l'action de l'utilisateur, vous pouvez stocker qu'une alarme a été créée ailleurs afin de savoir comment la recréer si nécessaire.

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 lorsqu'une nouvelle version de l'extension est installée :

service-worker.js:

chrome.runtime.onInstalled.addListener(async ({ reason }) => {
  // Create an alarm so we have something to look at in the demo
  await chrome.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1,
    persistAcrossSessions: true
  });
});

Répondre à une alarme

L'exemple suivant définit l'icône de la barre d'outils d'action action toolbar icon 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

    nombre facultatif

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

  • persistAcrossSessions

    booléen

    En attente

    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'un montant arbitraire au-delà de cette valeur.

AlarmCreateInfo

Propriétés

  • delayInMinutes

    nombre facultatif

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

  • periodInMinutes

    nombre facultatif

    Si cette valeur 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 cette valeur n'est pas définie, l'alarme ne se déclenchera qu'une seule fois.

  • persistAcrossSessions

    booléen facultatif

    En attente

    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

    nombre facultatif

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

Méthodes

clear()

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

Efface l'alarme portant le nom donné.

Paramètres

  • nom

    chaîne facultative

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

Renvoie

  • Promise<boolean>

    Chrome 91+

clearAll()

chrome.alarms.clearAll(): Promise<boolean>

Efface toutes les alarmes.

Renvoie

  • Promise<boolean>

    Chrome 91+

create()

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

Crée une alarme. L'événement onAlarm se déclenche à 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 cette alarme.

Pour réduire la charge sur la machine de l'utilisateur, Chrome limite les alarmes à une fois toutes les 30 secondes au maximum, mais peut les retarder d'un montant arbitraire. Autrement dit, définir delayInMinutes ou periodInMinutes sur une valeur inférieure à 0.5 ne sera pas respecté et entraînera un avertissement. when peut être défini sur une valeur inférieure à 30 secondes après "maintenant" sans avertissement, mais ne déclenchera pas l'alarme avant au moins 30 secondes.

Pour vous aider à déboguer votre application ou votre extension, lorsque 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

  • nom

    chaîne facultative

    Nom facultatif permettant d'identifier cette alarme. La valeur par défaut est la 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épétée, periodInMinutes est utilisé par défaut pour delayInMinutes.

Renvoie

  • Promise<void>

    Chrome 111+

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

get()

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

Récupère des informations sur l'alarme spécifiée.

Paramètres

  • nom

    chaîne facultative

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

Renvoie

  • Promise<Alarm | undefined>

    Chrome 91+

getAll()

chrome.alarms.getAll(): Promise<Alarm[]>

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

Renvoie

  • Promise<Alarm[]>

    Chrome 91+

Événements

onAlarm

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

Se déclenche lorsqu'une alarme a expiré. Utile pour les pages d'événements.

Paramètres

  • callback

    fonction

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

    (alarm: Alarm) => void