chrome.alarms

Beschreibung

Mit der chrome.alarms API planen Sie, dass Code regelmäßig oder zu einem bestimmten Zeitpunkt in der Zukunft ausgeführt wird.

Berechtigungen

alarms

Um die chrome.alarms API zu verwenden, deklarieren Sie die Berechtigung "alarms" im Manifest:

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

Konzepte und Nutzung

Damit zuverlässiges Verhalten gewährleistet werden kann, ist es hilfreich, das Verhalten der API zu verstehen.

Ruhemodus des Geräts

Der Wecker läuft weiter, während das Gerät schläft. Ein Gerät wird durch einen Wecker jedoch nicht aktiviert. Wenn das Gerät aktiviert wird, werden alle verpassten Wecker ausgelöst. Sich wiederholende Alarme werden höchstens einmal ausgelöst und dann für den angegebenen Zeitraum ab dem Aufwachen des Geräts neu geplant. Zeit, die seit der ursprünglichen Einstellung des Alarms bereits vergangen ist, werden dabei nicht berücksichtigt.

Persistenz

Alarme bleiben in der Regel so lange bestehen, bis eine Erweiterung aktualisiert wird. Dies ist jedoch nicht garantiert und Alarme werden möglicherweise gelöscht, wenn der Browser neu gestartet wird. Daher sollten Sie beim Erstellen eines Alarms einen Speicherwert festlegen und prüfen, ob er bei jedem Start des Service Workers vorhanden ist. Beispiel:

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();

Beispiele

Die folgenden Beispiele zeigen, wie ein Alarm verwendet und reagiert wird. Wenn Sie diese API ausprobieren möchten, installieren Sie das Alarm API-Beispiel aus dem Repository chrome-extension-sample.

Wecker stellen

Im folgenden Beispiel wird ein Alarm im Service Worker festgelegt, wenn die Erweiterung installiert wird:

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
  });
});

Auf Wecker reagieren

Im folgenden Beispiel wird das Symbol für die Aktionssymbolleiste basierend auf dem Namen des ausgelösten Weckers festgelegt.

service-worker.js:

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

Typen

Alarm

Attribute

  • name

    String

    Name dieses Weckers.

  • periodInMinutes

    Nummer optional

    Wenn nicht null, ist der Wecker ein sich wiederholender Weckruf und wird in periodInMinutes Minuten noch einmal ausgelöst.

  • scheduledTime

    Zahl

    Zeitpunkt, zu dem dieser Alarm laut Plan ausgelöst werden sollte, in Millisekunden über die Epoche hinaus (z.B. Date.now() + n). Aus Leistungsgründen wurde der Alarm möglicherweise um einen beliebigen anderen Wert verzögert.

AlarmCreateInfo

Attribute

  • delayInMinutes

    Nummer optional

    Zeitraum in Minuten, nach dem das onAlarm-Ereignis ausgelöst werden soll.

  • periodInMinutes

    Nummer optional

    Wenn festgelegt, sollte das onAlarm-Ereignis alle periodInMinutes Minuten nach dem durch when oder delayInMinutes festgelegten Anfangsereignis ausgelöst werden. Wird die Richtlinie nicht konfiguriert, wird der Alarm nur einmal ausgelöst.

  • wenn

    Nummer optional

    Zeitpunkt, zu dem der Alarm ausgelöst werden soll, in Millisekunden über die Epoche (z.B. Date.now() + n).

Methoden

clear()

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

Löscht den Alarm mit dem angegebenen Namen.

Parameter

  • name

    String optional

    Der Name des zu löschenden Weckers. Die Standardeinstellung ist der leere String.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (wasCleared: boolean)=>void

    • wasCleared

      boolean

Returns

  • Promise<boolean>

    Chrome 91 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

clearAll()

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

Löscht alle Wecker.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (wasCleared: boolean)=>void

    • wasCleared

      boolean

Returns

  • Promise<boolean>

    Chrome 91 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

create()

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

Wecker wird erstellt. Ungefähr zu den in alarmInfo angegebenen Zeiten wird das Ereignis onAlarm ausgelöst. Ist ein weiterer Alarm mit demselben Namen (oder keinem Namen, falls keiner angegeben ist) vorhanden, wird er abgebrochen und durch diesen Alarm ersetzt.

Um die Auslastung des Geräts des Nutzers zu reduzieren, begrenzt Chrome Alarme auf höchstens alle 30 Sekunden, kann sie jedoch um eine beliebige Zahl verzögern. Das heißt, wenn Sie delayInMinutes oder periodInMinutes auf einen niedrigeren Wert als 0.5 setzen, wird dies nicht berücksichtigt und führt zu einer Warnung. „when“ kann auf weniger als 30 Sekunden nach „jetzt“ ohne Warnung festgelegt werden. Dadurch wird der Alarm aber nicht für mindestens 30 Sekunden ausgelöst.

Um Fehler in Ihrer App oder Erweiterung zu beheben, ist die Häufigkeit, mit der der Alarm ausgelöst werden kann, unbegrenzt.

Parameter

  • name

    String optional

    Optionaler Name zur Identifizierung dieses Alarms. Die Standardeinstellung ist der leere String.

  • alarmInfo

    AlarmCreateInfo

    Beschreibt, wann der Alarm ausgelöst werden soll. Die Anfangszeit muss entweder durch when oder delayInMinutes angegeben werden (nicht aber beides). Wenn „periodInMinutes“ festgelegt ist, wird der Wecker nach dem ersten Ereignis alle periodInMinutes Minuten wiederholt. Wenn für einen sich wiederholenden Wecker weder when noch delayInMinutes festgelegt ist, wird periodInMinutes als Standardeinstellung für delayInMinutes verwendet.

  • callback

    Funktion optional

    Chrome 111 und höher

    Der Parameter callback sieht so aus: 

    ()=>void

Returns

  • Promise<void>

    Chrome 111 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

get()

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

Ruft Details zum angegebenen Alarm ab.

Parameter

  • name

    String optional

    Der Name des abzurufenden Weckers. Die Standardeinstellung ist der leere String.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (alarm?: Alarm)=>void

Returns

  • Promise<Alarm|nicht definiert>

    Chrome 91 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

getAll()

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

Ruft ein Array aller Alarme ab.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (alarms: Alarm[])=>void

Returns

  • Promise<Alarm[]>

    Chrome 91 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

Veranstaltungen

onAlarm

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

Wird ausgelöst, wenn ein Alarm abgelaufen ist Nützlich für Veranstaltungsseiten.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (alarm: Alarm)=>void