chrome.alarms

Description

Utilisez l'API chrome.alarms pour planifier l'exécution du code de manière périodique ou à une heure précise à l'avenir.

Autorisations

alarms

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

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

Concepts et utilisation

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

Veille de l'appareil

Les alarmes continuent de fonctionner lorsque l'appareil est en mode veille. Toutefois, une alarme ne réveille 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 utilisant 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

Les alarmes persistent généralement jusqu'à ce qu'une extension soit mise à jour. Toutefois, cela n'est pas garanti, et les alarmes peuvent être effacées lorsque le navigateur est redémarré. Par conséquent, envisagez de définir une valeur dans le stockage lorsqu'une alarme est créée, puis assurez-vous qu'elle existe chaque fois que votre service worker démarre. Exemple :

const STORAGE_KEY = "user-preference-alarm-enabled";

async function checkAlarmState() {
  const { alarmEnabled } = await chrome.storage.get(STORAGE_KEY);

  if (alarmEnabled) {
    const alarm = await chrome.alarms.get("my-alarm");

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

checkAlarmState();

Exemples

Les exemples suivants montrent comment utiliser et répondre à une alarme. 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éagir à une alarme

L'exemple suivant définit l'icône de la barre d'outils d'action en fonction du nom de l'alarme 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 une alarme répétitive et se déclenchera à nouveau dans periodInMinutes minutes.

  • scheduledTime

    Nombre

    Heure à laquelle cette alarme devait se déclencher, en millisecondes après l'époque (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 point.

AlarmCreateInfo

Propriétés

  • delayInMinutes

    number facultatif

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

  • periodInMinutes

    number 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 ce champ n'est pas défini, l'alarme ne se déclenche qu'une seule fois.

  • when

    number facultatif

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

Méthodes

clear()

Promesse 
chrome.alarms.clear(
  name?: string,
  callback?: function,
)

Efface l'alarme avec le nom donné.

Paramètres

  • nom

    chaîne facultatif

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

  • rappel

    fonction 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 sont compatibles avec la version 3 du fichier manifeste et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse se résout avec le même type que celui transmis au rappel.

clearAll()

Promesse 
chrome.alarms.clearAll(
  callback?: function,
)

Efface toutes les alarmes.

Paramètres

  • rappel

    fonction 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 sont compatibles avec la version 3 du fichier manifeste et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse se résout avec le même type que celui transmis au rappel.

create()

Promesse 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

Crée une alarme. À l'approche de l'heure ou des heures spécifiées par alarmInfo, l'événement onAlarm est déclenché. Si une autre alarme porte le même nom (ou si aucun nom n'est spécifié), elle sera 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 durée arbitraire supplémentaire. Autrement dit, définir delayInMinutes ou periodInMinutes sur une valeur inférieure à 0.5 ne sera pas pris en compte et entraînera un avertissement. when peut être défini sur moins de 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 votre extension, lorsque vous l'avez chargée sans l'extraire, 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 la chaîne vide.

  • alarmInfo

    AlarmCreateInfo

    Indique quand 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 déclenche toutes les periodInMinutes minutes après l'événement initial. Si ni when, ni delayInMinutes n'est défini pour une alarme récurrente, periodInMinutes est utilisé par défaut pour delayInMinutes.

  • rappel

    fonction facultatif

    Chrome 111 ou version ultérieure

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

    () => void

Renvoie

  • Promise<void>

    Chrome 111 ou version ultérieure

    Les promesses sont compatibles avec la version 3 du fichier manifeste et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse se résout avec le même type que celui transmis au rappel.

get()

Promesse 
chrome.alarms.get(
  name?: string,
  callback?: function,
)

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

Paramètres

  • nom

    chaîne facultatif

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

  • rappel

    fonction 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 sont compatibles avec la version 3 du fichier manifeste et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse se résout avec le même type que celui transmis au rappel.

getAll()

Promesse 
chrome.alarms.getAll(
  callback?: function,
)

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

Paramètres

  • rappel

    fonction facultatif

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

    (alarms: Alarm[]) => void

Renvoie

  • Promise<Alarm[]>

    Chrome 91 et versions ultérieures

    Les promesses sont compatibles avec la version 3 du fichier manifeste et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse se résout avec le même type que celui transmis au rappel.

Événements

onAlarm

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

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

Paramètres

  • rappel

    fonction

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

    (alarm: Alarm) => void