chrome.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 chrome.alarms API verwenden möchten, deklarieren Sie die "alarms" Berechtigung 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

Alarme werden weiterhin ausgeführt, während sich ein Gerät im Ruhemodus befindet. Ein Alarm kann ein Gerät jedoch nicht aufwecken. Wenn das Gerät aufwacht, werden alle verpassten Alarme ausgelöst. Wiederholende Alarme werden höchstens einmal ausgelöst und dann mit dem angegebenen Zeitraum ab dem Zeitpunkt des Aufwachens des Geräts neu geplant. Dabei wird keine Zeit berücksichtigt, die seit der ursprünglichen Festlegung des Alarms bereits vergangen ist.

Persistenz

Sie können die Persistenz eines Alarms bei der Erstellung mit dem persistAcrossSessions Flag steuern. Dieses Flag kann auf true (bleibt bis zur Aktualisierung der Erweiterung erhalten) oder false (wird gelöscht, wenn die Erweiterung neu geladen oder der Browser neu gestartet wird und immer dann, wenn die Erweiterung aktualisiert wird) gesetzt werden.

Andere Browser und frühere Chrome-Versionen

Diese Property wird in anderen Browsern (Problem) oder in Chrome-Versionen vor Chrome 150 nicht unterstützt. Das Verhalten kann unvorhersehbar sein. Daher sollten Sie dafür sorgen, dass wichtige Alarme bei jedem Start Ihres Service Workers vorhanden sind. Beispiel:

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

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

checkAlarmState();

Wenn Ihr Alarm dynamisch basierend auf einer Nutzeraktion erstellt wird, sollten Sie speichern, dass ein Alarm an anderer Stelle erstellt wurde, damit Sie ihn bei Bedarf neu erstellen können.

Beispiele

In den folgenden Beispielen wird gezeigt, wie Sie einen Alarm verwenden und darauf reagieren. Wenn Sie diese API testen möchten, installieren Sie das Beispiel für die Alarm API 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:

chrome.runtime.onInstalled.addListener(async ({ reason }) => {
  // Create an alarm so we have something to look at in the demo
  await chrome.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1,
    persistAcrossSessions: true
  });
});

Auf einen Alarm reagieren

Im folgenden Beispiel wird das Symbol der Aktionsleiste basierend auf dem Namen des ausgelösten Alarms festgelegt.

service-worker.js:

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

Typen

Alarm

Properties

  • name

    String

    Name dieses Alarms.

  • periodInMinutes

    Zahl optional

    Wenn nicht null, ist der Alarm ein wiederholender Alarm und wird nach periodInMinutes Minuten erneut ausgelöst.

  • persistAcrossSessions

    boolean

    Ausstehend

    Gibt an, ob der Alarm über Sitzungen hinweg (Browserneustarts) erhalten bleiben soll.

  • scheduledTime

    Zahl

    Zeit, zu der dieser Alarm ausgelöst werden sollte, in Millisekunden seit der Epoche (z.B. Date.now() + n). Aus Leistungsgründen wurde der Alarm möglicherweise um eine beliebige Zeit darüber hinaus verzögert.

AlarmCreateInfo

Properties

  • delayInMinutes

    Zahl optional

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

  • periodInMinutes

    Zahl optional

    Wenn festgelegt, wird das Ereignis „onAlarm“ alle periodInMinutes Minuten nach dem ersten Ereignis ausgelöst, das durch when oder delayInMinutes angegeben wird. Wenn nicht festgelegt, wird der Alarm nur einmal ausgelöst.

  • persistAcrossSessions

    Boolescher Wert optional

    Ausstehend

    Gibt an, ob der Alarm über Sitzungen hinweg (Browserneustarts) erhalten bleiben soll. In Chrome ist diese Einstellung standardmäßig auf „true“ gesetzt, um dem bisherigen Verhalten zu entsprechen. Sie sollten sie jedoch explizit festlegen, um die Kompatibilität mit verschiedenen Browsern zu maximieren.

  • when

    Zahl 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. Standardmäßig ist dies ein leerer String.

Ausgabe

  • Promise<boolean>

    Chrome 91+

clearAll()

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

Löscht alle Alarme.

Ausgabe

  • Promise<boolean>

    Chrome 91+

create()

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

Erstellt einen Alarm. Zu den in alarmInfo angegebenen Zeiten wird das Ereignis onAlarm ausgelöst. Wenn ein anderer Alarm mit demselben Namen vorhanden ist (oder ohne Namen, wenn keiner angegeben ist), wird er abgebrochen und durch diesen Alarm ersetzt.

Um die Last auf dem Computer des Nutzers zu verringern, beschränkt Chrome Alarme auf höchstens einmal alle 30 Sekunden, kann sie aber auch um eine beliebige Zeit verzögern. Wenn Sie delayInMinutes oder periodInMinutes auf weniger als 0.5 setzen, wird dies nicht berücksichtigt und es wird eine Warnung angezeigt. when kann ohne Warnung auf weniger als 30 Sekunden nach „jetzt“ gesetzt werden, löst den Alarm aber erst nach mindestens 30 Sekunden aus.

Wenn Sie Ihre App oder Erweiterung entpackt geladen haben, gibt es keine Beschränkung, wie oft der Alarm ausgelöst werden kann. Das kann beim Debuggen hilfreich sein.

Parameter

  • name

    String optional

    Optionaler Name zur Identifizierung dieses Alarms. Standardmäßig ist dies ein leerer String.

  • alarmInfo

    AlarmCreateInfo

    Beschreibt, wann der Alarm ausgelöst werden soll. Die Anfangszeit muss entweder mit when oder delayInMinutes angegeben werden (aber nicht mit beiden). Wenn periodInMinutes festgelegt ist, wird der Alarm alle periodInMinutes Minuten nach dem ersten Ereignis wiederholt. Wenn für einen 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 Alarm 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. Standardmäßig ist dies ein leerer String.

Ausgabe

  • Promise<Alarm | undefined>

    Chrome 91+

getAll()

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

Ruft ein Array aller Alarme ab.

Ausgabe

  • Promise<Alarm[]>

    Chrome 91+

Ereignisse

onAlarm

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

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

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (alarm: Alarm) => void