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

Deklarieren Sie zur Verwendung der chrome.alarms API die Berechtigung "alarms" im Manifest:

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

Konzepte und Verwendung

Um ein zuverlässiges Verhalten zu gewährleisten, ist es hilfreich, das Verhalten der API zu verstehen.

Ruhemodus des Geräts

Der Wecker wird auch im Ruhezustand des Geräts aktiviert. Ein Wecker wird jedoch nicht um das Gerät aufzuwecken. Wenn das Gerät aktiviert wird, werden alle verpassten Wecker ausgelöst. Wiederholte Alarme werden höchstens einmal ausgelöst und dann neu geplant mithilfe der festgelegter Zeitraum ab dem Ruhemodus des Geräts, ohne Berücksichtigung Zeitpunkt, der bereits verstrichen ist, seit der Alarm ursprünglich aktiviert wurde.

Persistenz

Alarme bleiben in der Regel bestehen, bis eine Erweiterung aktualisiert wird. Dies ist jedoch nicht garantiert. wird möglicherweise gelöscht, wenn der Browser neu gestartet wird. Sie sollten daher einen Speicherwert festlegen wenn ein Alarm erstellt wird, und achten Sie darauf, dass 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 du einen Alarm verwendest und darauf reagierst. Um diese API auszuprobieren, Installieren Sie das Alarm API-Beispiel unter chrome-extension-samples zu erstellen.

Wecker stellen

Mit dem folgenden Beispiel wird bei der Installation der Erweiterung ein Alarm im Service Worker ausgelöst:

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 Alarm reagieren

Im folgenden Beispiel wird das Symbol in der Aktionssymbolleiste auf den Namen des ausgelösten Alarms ausgerichtet.

service-worker.js:

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

Typen

Alarm

Attribute

  • Name

    String

    Name dieses Alarms.

  • periodInMinutes

    Zahl optional

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

  • scheduledTime

    Zahl

    Zeitpunkt, zu dem dieser Alarm ausgelöst werden sollte, in Millisekunden nach der Epoche (z.B. Date.now() + n). Aus Leistungsgründen kann der Alarm noch um etwas länger verzögert worden sein.

AlarmCreateInfo

Attribute

  • delayInMinutes

    Zahl optional

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

  • periodInMinutes

    Zahl optional

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

  • wann

    Zahl optional

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

Methoden

clear()

<ph type="x-smartling-placeholder"></ph> 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 Alarms. Die Standardeinstellung ist ein leerer String.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (wasCleared: boolean) => void

    • wasCleared

      boolean

Gibt Folgendes zurück:

  • Promise&lt;boolean&gt;

    Chrome 91 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

clearAll()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.alarms.clearAll(
  callback?: function,
)

Löscht alle Wecker.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (wasCleared: boolean) => void

    • wasCleared

      boolean

Gibt Folgendes zurück:

  • Promise&lt;boolean&gt;

    Chrome 91 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

create()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

Wecker stellen Kurz nach der in alarmInfo angegebenen Zeit wird das Ereignis onAlarm ausgelöst. Gibt es einen anderen Alarm mit dem gleichen Namen (oder keinen Namen, wenn keiner angegeben ist), wird er abgebrochen und durch diesen Wecker ersetzt.

Um die Geräte des Nutzers zu entlasten, beschränkt Chrome Alarme auf höchstens einmal alle 30 Sekunden, kann aber auch um einiges länger verzögern. Wenn Sie also delayInMinutes oder periodInMinutes auf weniger als 0.5 festlegen, wird dies nicht berücksichtigt und es wird eine Warnung ausgelöst. when kann auf weniger als 30 Sekunden nach „jetzt“ festgelegt werden ohne Vorwarnung. Der Alarm löst jedoch erst nach 30 Sekunden einen Alarm aus.

Um Sie bei der Fehlerbehebung Ihrer App oder Erweiterung zu unterstützen, gibt es keine Begrenzung dafür, wie oft der Alarm ausgelöst werden kann, nachdem Sie sie entpackt geladen haben.

Parameter

  • Name

    String optional

    Optionaler Name zur Identifizierung dieses Alarms. Die Standardeinstellung ist ein leerer String.

  • alarmInfo

    AlarmCreateInfo

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

  • callback

    Funktion optional

    Chrome 111 und höher

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 111 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

get()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.alarms.get(
  name?: string,
  callback?: function,
)

Ruft Details zum angegebenen Alarm ab.

Parameter

  • Name

    String optional

    Der Name des abzurufenden Alarms. Die Standardeinstellung ist ein leerer String.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (alarm?: Alarm) => void

Gibt Folgendes zurück:

  • Promise&lt;Alarm | nicht definiert>

    Chrome 91 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

getAll()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.alarms.getAll(
  callback?: function,
)

Ruft ein Array aller Alarme ab.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (alarms: Alarm[]) => void

Gibt Folgendes zurück:

  • Versprechen<Alarm[]>

    Chrome 91 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback ü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: <ph type="x-smartling-placeholder"></ph>

    (alarm: Alarm) => void