chrome.alarms

Beschreibung

Mit der chrome.alarms API können Sie Code planen, der regelmäßig oder zu einer bestimmten Zeit in der Zukunft ausgeführt werden soll.

Berechtigungen

alarms

Wenn Sie die chrome.alarms API verwenden möchten, müssen Sie die Berechtigung "alarms" im manifest angeben:

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

Konzepte und Verwendung

Damit die API zuverlässig funktioniert, ist es hilfreich, das Verhalten der API zu verstehen.

Ruhemodus des Geräts

Wecker werden auch dann ausgeführt, wenn das Gerät im Ruhemodus ist. Ein Wecker weckt das Gerät jedoch nicht auf. Wenn das Gerät aktiviert wird, werden alle verpassten Wecker ausgelöst. Wiederholte Wecker werden höchstens einmal ausgelöst und dann mit dem angegebenen Zeitraum neu geplant, beginnend mit dem Zeitpunkt, zu dem das Gerät aktiviert wird. Dabei wird die Zeit nicht berücksichtigt, die bereits verstrichen ist, seit der Wecker ursprünglich eingestellt wurde.

Persistenz

Alarme bleiben in der Regel erhalten, bis eine Erweiterung aktualisiert wird. Dies ist jedoch nicht garantiert und Wecker können beim Neustart des Browsers gelöscht werden. Legen Sie daher beim Erstellen eines Weckers einen Wert im Speicher fest und achten Sie darauf, dass er jedes Mal vorhanden ist, wenn Ihr Dienstarbeiter gestartet wird. 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

In den folgenden Beispielen wird gezeigt, wie Sie einen Wecker verwenden und darauf reagieren. Wenn Sie diese API ausprobieren möchten, installieren Sie das Beispiel für die Wecker API aus dem Repository chrome-extension-samples.

Wecker stellen

Im folgenden Beispiel wird im Service Worker ein Wecker gestellt, 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 einen Alarm reagieren

Im folgenden Beispiel wird das Symbol in der Symbolleiste für Aktionen 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

    number optional

    Wenn der Wert nicht null ist, ist der Wecker ein wiederkehrender Wecker und ertönt in periodInMinutes Minuten noch einmal.

  • scheduledTime

    Zahl

    Zeitpunkt, zu dem dieser Wecker ausgelöst werden soll, in Millisekunden seit der Epoche (z.B. Date.now() + n). Aus Leistungsgründen kann die Auslösung des Weckers um einen beliebigen Betrag verzögert worden sein.

AlarmCreateInfo

Attribute

  • delayInMinutes

    number optional

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

  • periodInMinutes

    number optional

    Wenn das Ereignis festgelegt ist, sollte das Ereignis „onAlarm“ alle periodInMinutes Minuten nach dem durch when oder delayInMinutes angegebenen ersten Ereignis ausgelöst werden. Wenn Sie diese Option nicht festlegen, wird der Wecker nur einmal ausgelöst.

  • wann

    number optional

    Die Zeit, zu der der Wecker klingeln soll, in Millisekunden seit der Epoche (z.B. Date.now() + n).

Methoden

clear()

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

Löscht den Wecker mit dem angegebenen Namen.

Parameter

  • name

    String optional

    Der Name des Weckers, der gelöscht werden soll. Standardmäßig ist der String leer.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (wasCleared: boolean) => void

    • wasCleared

      boolean

Gibt Folgendes zurück:

  • Promise<boolean>

    Chrome 91 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

clearAll()

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

Löscht alle Wecker.

Parameter

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (wasCleared: boolean) => void

    • wasCleared

      boolean

Gibt Folgendes zurück:

  • Promise<boolean>

    Chrome 91 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

create()

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

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

Um die Belastung des Computers des Nutzers zu verringern, begrenzt Chrome Wecker auf maximal einmal alle 30 Sekunden. Die Wecker können aber beliebig verzögert werden. Wenn Sie also delayInMinutes oder periodInMinutes auf einen Wert unter 0.5 festlegen, wird dies nicht berücksichtigt und es wird eine Warnung ausgegeben. when kann ohne Warnung auf weniger als 30 Sekunden nach „Jetzt“ festgelegt werden. Der Wecker wird jedoch erst nach mindestens 30 Sekunden ausgelöst.

Wenn Sie Ihre App oder Erweiterung entpackt geladen haben, kann der Alarm so oft ausgelöst werden, wie Sie möchten, um Ihnen beim Entfernen von Fehlern zu helfen.

Parameter

  • name

    String optional

    Optionaler Name zur Identifizierung dieses Alarms. Standardmäßig ist der String leer.

  • alarmInfo

    AlarmCreateInfo

    Beschreibt, wann der Wecker klingeln soll. Die Anfangszeit muss entweder when oder delayInMinutes sein, aber nicht beides. Wenn periodInMinutes festgelegt ist, wird der Wecker nach dem ersten Ereignis alle periodInMinutes Minuten wiederholt. Wenn weder when noch delayInMinutes für einen wiederkehrenden Wecker festgelegt ist, wird periodInMinutes als Standard für delayInMinutes verwendet.

  • callback

    function optional

    Chrome 111 und höher

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Promise<void>

    Chrome 111 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

get()

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

Ruft Details zum angegebenen Wecker ab.

Parameter

  • name

    String optional

    Der Name des Weckers, der abgerufen werden soll. Standardmäßig ist der String leer.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (alarm?: Alarm) => void

Gibt Folgendes zurück:

  • Promise<Alarm | undefined>

    Chrome 91 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

getAll()

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

Ruft ein Array aller Wecker ab.

Parameter

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (alarms: Alarm[]) => void

Gibt Folgendes zurück:

  • Promise<Alarm[]>

    Chrome 91 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

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