browser.alarms

Beschreibung

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

Berechtigungen

alarms

Wenn Sie die browser.alarms API verwenden möchten, deklarieren Sie die Berechtigung "alarms" im Manifest:

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

Konzepte und Verwendung

Um ein zuverlässiges Verhalten zu gewährleisten, ist es hilfreich, zu verstehen, wie sich die API verhält.

Ruhemodus des Geräts

Wecker funktionieren auch, wenn sich ein Gerät im Ruhemodus befindet. Ein Alarm weckt ein Gerät jedoch nicht auf. 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 neu geplant, beginnend mit dem Aufwachen des Geräts. Dabei wird die Zeit, die seit dem ursprünglichen Festlegen des Alarms bereits verstrichen ist, nicht berücksichtigt.

Persistenz

Sie können die Persistenz eines Alarms beim Erstellen mit dem Flag persistAcrossSessions steuern. Hierfür kann true (bleibt bestehen, bis die Erweiterung aktualisiert wird) oder false (wird gelöscht, wenn die Erweiterung neu geladen oder der Browser neu gestartet wird, und wenn die Erweiterung aktualisiert wird) festgelegt werden.

Andere Browser und ältere Chrome-Versionen

Diese Property wird in anderen Browsern (Problem) oder in Chrome-Versionen vor Chrome 150 nicht unterstützt. Das Verhalten kann in diesen Fällen unvorhersehbar sein. Daher ist es am besten, bei jedem Start des Service Workers dafür zu sorgen, dass wichtige Alarme vorhanden sind. Beispiel:

async function checkAlarmState() {
  const alarm = await browser.alarms.get("my-alarm");

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

checkAlarmState();

Wenn der Wecker dynamisch auf Grundlage einer Nutzeraktion erstellt wird, sollten Sie die Information, dass ein Wecker erstellt wurde, an anderer Stelle speichern, damit Sie ihn bei Bedarf neu erstellen können.

Beispiele

Die folgenden Beispiele zeigen, wie du einen Wecker verwendest und darauf reagierst. Wenn Sie diese API ausprobieren möchten, installieren Sie das Alarm API-Beispiel aus dem Repository chrome-extension-samples.

Wecker stellen

Im folgenden Beispiel wird ein Alarm im Service Worker festgelegt, wenn eine neue Version der Erweiterung installiert wird:

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

Auf einen Alarm reagieren

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

service-worker.js:

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

Typen

Alarm

Attribute

  • name

    String

    Name dieses Alarms.

  • periodInMinutes

    number optional

    Wenn der Wert nicht null ist, handelt es sich um einen wiederkehrenden Wecker, der in periodInMinutes Minuten wieder klingelt.

  • persistAcrossSessions

    boolean

    Chrome 150+

    Gibt an, ob der Alarm über Sitzungen (Browserneustarts) hinweg beibehalten werden soll.

  • scheduledTime

    Zahl

    Zeit, zu der dieser Alarm ausgelöst werden sollte, in Millisekunden nach der Epoche (z.B. Date.now() + n). Aus Leistungsgründen kann der Alarm um einen beliebigen Zeitraum verzögert worden sein.

AlarmCreateInfo

Attribute

  • delayInMinutes

    number optional

    Zeitspanne in Minuten, nach der das onAlarm-Ereignis ausgelöst werden soll.

  • name

    String optional

    Chrome 152 oder höher

    Name dieses Alarms.

  • periodInMinutes

    number optional

    Wenn festgelegt, sollte das onAlarm-Ereignis alle periodInMinutes Minuten nach dem ersten Ereignis ausgelöst werden, das durch when oder delayInMinutes angegeben wurde. Wenn Sie diese Option nicht festlegen, wird der Alarm nur einmal ausgelöst.

  • persistAcrossSessions

    Boolesch optional

    Chrome 150+

    Gibt an, ob der Alarm über Sitzungen (Browserneustarts) hinweg beibehalten werden soll. In Chrome ist dies standardmäßig auf „true“ gesetzt, um dem bisherigen Verhalten zu entsprechen. Sie sollten dies jedoch explizit festlegen, um die Kompatibilität zwischen Browsern zu maximieren.

  • wann

    number optional

    Zeit, zu der der Alarm ausgelöst werden soll, in Millisekunden seit der Epoche (z.B. Date.now() + n).

Methoden

clear()

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

Löscht den Alarm mit dem angegebenen Namen.

Parameter

  • name

    String optional

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

Ausgabe

  • Promise<boolean>

    Chrome 91 oder höher

clearAll()

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

Löscht alle Wecker.

Ausgabe

  • Promise<boolean | undefined>

    Chrome 91 oder höher

create()

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

Erstellt einen Wecker. In der Nähe der von alarmInfo angegebenen Zeit(en) wird das Ereignis onAlarm ausgelöst. Wenn es einen anderen Wecker mit demselben Namen gibt (oder ohne Namen, falls keiner angegeben ist), wird er abgebrochen und durch diesen Wecker ersetzt.

Um die Belastung des Computers des Nutzers zu reduzieren, beschränkt Chrome die Alarme auf höchstens einmal pro Sekunde, kann sie aber auch um einen beliebigen Betrag verzögern. Wenn Sie delayInMinutes oder periodInMinutes auf weniger als 1 Sekunde festlegen, wird dies nicht berücksichtigt und es wird eine Warnung ausgegeben. when kann ohne Warnung auf weniger als 1 Sekunde nach „jetzt“ festgelegt werden, der Wecker wird jedoch erst nach mindestens 1 Sekunde ausgelöst.

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 Startzeit muss entweder mit when oder delayInMinutes angegeben werden (aber nicht mit beiden). Wenn periodInMinutes festgelegt ist, wird der Alarm nach dem ersten Ereignis alle periodInMinutes Minuten wiederholt. Wenn für einen sich wiederholenden Alarm weder when noch delayInMinutes festgelegt ist, wird periodInMinutes als Standardwert für delayInMinutes verwendet.

Ausgabe

  • Promise<void>

    Chrome 111+

    Promise, das aufgelöst wird, wenn der Wecker erstellt wurde.

get()

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

Ruft Details zum angegebenen Alarm ab.

Parameter

  • name

    String optional

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

Ausgabe

  • Promise<Alarm | undefined>

    Chrome 91 oder höher

getAll()

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

Ruft ein Array aller Alarme ab.

Ausgabe

  • Promise<Alarm[]>

    Chrome 91 oder höher

Ereignisse

onAlarm

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

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

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (alarm: Alarm) => void