chrome.alarms

Beschreibung

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

Berechtigungen

alarms

Manifest

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

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

Beispiele

Die folgenden Beispiele zeigen, wie Sie einen Alarm verwenden und darauf reagieren. 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 beim Installieren der Erweiterung ein Alarm im Service Worker festgelegt:

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 für die 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 Weckers.

  • periodInMinutes

    number optional

    Wenn nicht null, ist der Alarm ein sich wiederholender Alarm und wird in periodInMinutes Minuten wieder ausgelöst.

  • persistAcrossSessions

    boolean

    Ausstehend

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

  • scheduledTime

    Zahl

    Zeit, zu der dieser Alarm ausgelöst werden sollte, in Millisekunden seit dem Epochenbeginn (z.B. Date.now() + n). Aus Leistungsgründen kann der Alarm um eine beliebige Zeit darüber hinaus verzögert worden sein.

AlarmCreateInfo

Properties

  • delayInMinutes

    number optional

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

  • periodInMinutes

    number optional

    Wenn festgelegt, sollte das onAlarm-Ereignis alle periodInMinutes Minuten nach dem ursprünglichen Ereignis ausgelöst werden, das durch when oder delayInMinutes angegeben wird. Wenn diese Option nicht festgelegt ist, wird der Alarm nur einmal ausgelöst.

  • persistAcrossSessions

    Boolesch optional

    Ausstehend

    Gibt an, ob der Alarm über Sitzungen hinweg (Browserneustarts) bestehen bleiben soll. In Chrome ist der Standardwert „true“, um dem bisherigen Verhalten zu entsprechen. Sie sollten ihn jedoch explizit festlegen, um die browserübergreifende Kompatibilität zu maximieren.

  • wann

    number optional

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

Methoden

clear()

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

Löscht den Wecker mit dem angegebenen Namen.

Parameter

  • name

    String optional

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

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (wasCleared: boolean) => void

    • wasCleared

      boolean

Ausgabe

  • Promise<boolean>

    Chrome 91 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

clearAll()

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

Löscht alle Wecker.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (wasCleared: boolean) => void

    • wasCleared

      boolean

Ausgabe

  • Promise<boolean>

    Chrome 91 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

create()

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

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

Um die Belastung des Nutzergeräts zu verringern, werden Alarme in Chrome höchstens einmal alle 30 Sekunden ausgelöst. Sie können aber auch beliebig lange verzögert werden. Wenn Sie delayInMinutes oder periodInMinutes auf einen Wert unter 0.5 festlegen, wird dies nicht berücksichtigt und es wird eine Warnung angezeigt. when kann ohne Warnung auf weniger als 30 Sekunden nach „jetzt“ eingestellt werden. Der Alarm wird jedoch erst nach mindestens 30 Sekunden ausgelöst.

Wenn Sie Ihre App oder Erweiterung entpackt geladen haben, gibt es keine Begrenzung, wie oft der Alarm ausgelöst werden kann. Das kann Ihnen beim Debuggen helfen.

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 alle periodInMinutes Minuten nach dem ursprünglichen Ereignis wiederholt. Wenn weder when noch delayInMinutes für einen sich wiederholenden Wecker festgelegt ist, wird periodInMinutes als Standard für delayInMinutes verwendet.

  • callback

    Funktion optional

    Chrome 111 und höher

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 111 und höher

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

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

get()

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

Ruft Details zum angegebenen Wecker 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

Ausgabe

  • Promise<Alarm | undefined>

    Chrome 91 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getAll()

Promise 
chrome.alarms.getAll(
  callback?: function,
): Promise<Alarm[]>

Ruft ein Array aller Wecker ab.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (alarms: Alarm[]) => void

Ausgabe

  • Promise<Alarm[]>

    Chrome 91 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

Ereignisse

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