Beschreibung
Mit der chrome.alarms
API planen Sie, dass Code regelmäßig oder zu einem bestimmten Zeitpunkt in der Zukunft ausgeführt wird.
Berechtigungen
alarms
Um die chrome.alarms
API zu verwenden, deklarieren Sie die Berechtigung "alarms"
im Manifest:
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
Konzepte und Nutzung
Damit zuverlässiges Verhalten gewährleistet werden kann, ist es hilfreich, das Verhalten der API zu verstehen.
Ruhemodus des Geräts
Der Wecker läuft weiter, während das Gerät schläft. Ein Gerät wird durch einen Wecker jedoch nicht aktiviert. 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 ab dem Aufwachen des Geräts neu geplant. Zeit, die seit der ursprünglichen Einstellung des Alarms bereits vergangen ist, werden dabei nicht berücksichtigt.
Persistenz
Alarme bleiben in der Regel so lange bestehen, bis eine Erweiterung aktualisiert wird. Dies ist jedoch nicht garantiert und Alarme werden möglicherweise gelöscht, wenn der Browser neu gestartet wird. Daher sollten Sie beim Erstellen eines Alarms einen Speicherwert festlegen und prüfen, ob 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 ein Alarm verwendet und reagiert wird. Wenn Sie diese API ausprobieren möchten, installieren Sie das Alarm API-Beispiel aus dem Repository chrome-extension-sample.
Wecker stellen
Im folgenden Beispiel wird ein Alarm im Service Worker festgelegt, 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 Wecker reagieren
Im folgenden Beispiel wird das Symbol für die Aktionssymbolleiste 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
Nummer optional
Wenn nicht null, ist der Wecker ein sich wiederholender Weckruf und wird in
periodInMinutes
Minuten noch einmal ausgelöst. -
scheduledTime
Zahl
Zeitpunkt, zu dem dieser Alarm laut Plan ausgelöst werden sollte, in Millisekunden über die Epoche hinaus (z.B.
Date.now() + n
). Aus Leistungsgründen wurde der Alarm möglicherweise um einen beliebigen anderen Wert verzögert.
AlarmCreateInfo
Attribute
-
delayInMinutes
Nummer optional
Zeitraum in Minuten, nach dem das
onAlarm
-Ereignis ausgelöst werden soll. -
periodInMinutes
Nummer optional
Wenn festgelegt, sollte das onAlarm-Ereignis alle
periodInMinutes
Minuten nach dem durchwhen
oderdelayInMinutes
festgelegten Anfangsereignis ausgelöst werden. Wird die Richtlinie nicht konfiguriert, wird der Alarm nur einmal ausgelöst. -
wenn
Nummer optional
Zeitpunkt, zu dem der Alarm ausgelöst werden soll, in Millisekunden über die Epoche (z.B.
Date.now() + n
).
Methoden
clear()
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 Weckers. Die Standardeinstellung ist der leere String.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(wasCleared: boolean) => void
-
wasCleared
boolean
-
Rückgabe
-
Promise<boolean>
Chrome 91 und höherPromise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
Löscht alle Wecker.
Parameter
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(wasCleared: boolean) => void
-
wasCleared
boolean
-
Rückgabe
-
Promise<boolean>
Chrome 91 und höherPromise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
)
Wecker wird erstellt. Ungefähr zu den in alarmInfo
angegebenen Zeiten wird das Ereignis onAlarm
ausgelöst. Ist ein weiterer Alarm mit demselben Namen (oder keinem Namen, falls keiner angegeben ist) vorhanden, wird er abgebrochen und durch diesen Alarm ersetzt.
Um die Auslastung des Geräts des Nutzers zu reduzieren, begrenzt Chrome Alarme auf höchstens alle 30 Sekunden, kann sie jedoch um eine beliebige Zahl verzögern. Das heißt, wenn Sie delayInMinutes
oder periodInMinutes
auf einen niedrigeren Wert als 0.5
setzen, wird dies nicht berücksichtigt und führt zu einer Warnung. „when
“ kann auf weniger als 30 Sekunden nach „jetzt“ ohne Warnung festgelegt werden. Dadurch wird der Alarm aber nicht für mindestens 30 Sekunden ausgelöst.
Um Fehler in Ihrer App oder Erweiterung zu beheben, ist die Häufigkeit, mit der der Alarm ausgelöst werden kann, unbegrenzt.
Parameter
-
name
String optional
Optionaler Name zur Identifizierung dieses Alarms. Die Standardeinstellung ist der leere String.
-
alarmInfo
Beschreibt, wann der Alarm ausgelöst werden soll. Die Anfangszeit muss entweder durch
when
oderdelayInMinutes
angegeben werden (nicht aber beides). Wenn „periodInMinutes
“ festgelegt ist, wird der Wecker nach dem ersten Ereignis alleperiodInMinutes
Minuten wiederholt. Wenn für einen sich wiederholenden Wecker wederwhen
nochdelayInMinutes
festgelegt ist, wirdperiodInMinutes
als Standardeinstellung fürdelayInMinutes
verwendet. -
callback
Funktion optional
Chrome 111 und höherDer Parameter
callback
sieht so aus:() => void
Rückgabe
-
Promise<void>
Chrome 111 und höherPromise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
Ruft Details zum angegebenen Alarm ab.
Parameter
Rückgabe
-
Promise<Alarm | undefined>
Chrome 91 und höherPromise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.
getAll()
chrome.alarms.getAll(
callback?: function,
)
Ruft ein Array aller Alarme ab.
Parameter
Rückgabe
-
Promise<Alarm[]>
Chrome 91 und höherPromise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.