browser.alarms

Description

Autorisations

Pour utiliser l'API browser.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 s'exécuter 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étitives se déclenchent au maximum une fois, puis sont reprogrammées en fonction de la période spécifiée à partir du moment où l'appareil se réactive, sans tenir compte du temps déjà écoulé depuis la configuration initiale de l'alarme.

Persistance

Vous pouvez contrôler la persistance d'une alarme au moment de sa création à l'aide de l'option persistAcrossSessions. Vous pouvez définir cette option sur true (persiste jusqu'à la mise à jour de l'extension) ou false (effacé si l'extension est actualisé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 les 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 browser.alarms.get("my-alarm");

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

checkAlarmState();

Si votre alarme est créée de manière dynamique en fonction d'une action de l'utilisateur, vous pouvez stocker le fait qu'une alarme a été créée ailleurs afin de savoir si vous devez 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 :

browser.runtime.onInstalled.addListener(async ({ reason }) => {
  // Create an alarm so we have something to look at in the demo
  await browser.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 en fonction du nom de l'alarme qui s'est déclenchée.

service-worker.js :

browser.alarms.onAlarm.addListener((alarm) => {
  browser.action.setIcon({
    path: getIconPath(alarm.name),
  });
});

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

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

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

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

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

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