chrome.alarms

Description

Utilisez l'API chrome.alarms pour planifier l'exécution du code à intervalles réguliers ou à une heure spécifique.

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.

Veille de l'appareil

Les alarmes continuent de fonctionner lorsqu'un appareil est en veille. Cependant, aucune alarme ne se déclenche activer un appareil. Lorsque l'appareil est réactivé, toutes les alarmes manquées se déclenchent. Les alarmes répétées se déclencheront une seule fois au maximum et seront reprogrammées à l'aide du période spécifiée à compter de l'activation de l'appareil, sans tenir compte à tout moment qui s'est écoulé depuis le début 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 peut être effacé au redémarrage du navigateur. Par conséquent, envisagez de définir une valeur pour l'espace de stockage. lorsqu'une alarme est créée, puis vérifiez 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 depuis chrome-extension-samples. un dépôt de clés.

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 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

    numéro facultatif

    Si la valeur n'est pas nulle, l'alarme est récurrente et se déclenchera 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 de façon arbitraire au-delà de cette valeur.

AlarmCreateInfo

Propriétés

  • delayInMinutes

    numéro facultatif

    Durée au terme de laquelle l'événement onAlarm doit se déclencher, en minutes.

  • 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éclenchera 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()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.alarms.clear(
  name?: string,
  callback?: function,
)

Efface l'alarme portant le nom donné.

Paramètres

  • nom

    chaîne facultatif

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

  • rappel

    function facultatif

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

    (wasCleared: boolean) => void

    • wasCleared

      booléen

Renvoie

  • Promise&lt;boolean&gt;

    Chrome 91 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

clearAll()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.alarms.clearAll(
  callback?: function,
)

Efface toutes les alarmes.

Paramètres

  • rappel

    function facultatif

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

    (wasCleared: boolean) => void

    • wasCleared

      booléen

Renvoie

  • Promise&lt;boolean&gt;

    Chrome 91 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

create()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

Crée une alarme. L'événement onAlarm est déclenché peu avant les 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.

Afin de réduire la charge sur l'ordinateur de l'utilisateur, Chrome limite les alarmes à une fois toutes les 30 secondes maximum, mais peut les retarder davantage. Autrement dit, si vous définissez delayInMinutes ou periodInMinutes sur une valeur inférieure à 0.5, ce paramètre ne sera pas appliqué et déclenchera un avertissement. when peut être défini sur moins de 30 secondes après "maintenant" sans avertissement préalable, mais sans déclencher l'alarme pendant au moins 30 secondes.

Pour vous aider à déboguer votre application ou votre extension, une fois chargées, 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 quand l'alarme doit se déclencher. L'heure initiale doit être spécifiée soit par when, soit par 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 aucune des alarmes when et delayInMinutes n'est définie pour une alarme récurrente, la valeur periodInMinutes est utilisée par défaut pour delayInMinutes.

  • rappel

    function facultatif

    Chrome 111 ou version ultérieure

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

    () => void

Renvoie

  • Promesse<void>

    Chrome 111 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

get()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.alarms.get(
  name?: string,
  callback?: function,
)

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.

  • rappel

    function facultatif

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

    (alarm?: Alarm) => void

Renvoie

  • Promise&lt;Alarm | indéfini>

    Chrome 91 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

getAll()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.alarms.getAll(
  callback?: function,
)

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

Paramètres

  • rappel

    function facultatif

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

    (alarms: Alarm[]) => void

Renvoie

  • Promesse<Alarme[]>

    Chrome 91 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La 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éclenchement au terme d'une alarme Utile pour les pages d'événements.

Paramètres

  • rappel

    fonction

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

    (alarm: Alarm) => void