chrome.alarms

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

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 comportement de l'API.

Sommeil de l'appareil

Les alarmes continuent de se déclencher lorsqu'un appareil est en veille. Cependant, une alarme ne réveille pas un appareil. Lorsque l'appareil se réactive, les alarmes manquées se déclenchent. Les alarmes répétées 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 s'active, sans prendre en compte le temps écoulé depuis que l'alarme a été initialement configurée.

Persistance

En général, les alarmes persistent jusqu'à ce qu'une extension soit mise à jour. Toutefois, cela n'est pas garanti, et les alarmes peuvent être effacées au redémarrage du navigateur. Par conséquent, envisagez de définir une valeur dans l'espace de stockage lorsqu'une alarme est créée, puis assurez-vous qu'elle existe à chaque démarrage du service worker. 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 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é par when ou delayInMinutes. 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()

Promesse 
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érieures

    Les promesses sont compatibles avec Manifest V3 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 est résolue 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 facultative

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

    (wasCleared: boolean)=>void

    • wasCleared

      boolean

Renvoie

  • Promise<boolean>

    Chrome 91 et versions ultérieures

    Les promesses sont compatibles avec Manifest V3 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 est résolue 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. À 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

    AlarmCreateInfo

    Décrit à quel moment l'alarme doit se déclencher. L'heure initiale doit être spécifiée avec when ou delayInMinutes (mais pas les deux). Si periodInMinutes est défini, l'alarme se répètera 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 facultative

    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

    Les promesses sont compatibles avec Manifest V3 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 est résolue avec le même type que celui transmis au rappel.

get()

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

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

Paramètres

  • name

    string facultatif

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

  • rappel

    fonction facultative

    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 Manifest V3 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 est résolue 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 facultative

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

    (alarms: Alarm[])=>void

Renvoie

  • Promesse<Alarme[]>

    Chrome 91 et versions ultérieures

    Les promesses sont compatibles avec Manifest V3 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 est résolue avec le même type que celui transmis au rappel.

Événements

onAlarm

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

Déclenché lorsqu'une alarme s'est écoulée Cette fonctionnalité est utile pour les pages d'événement.

Paramètres

  • rappel

    function

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

    (alarm: Alarm)=>void