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
alarmsWenn Sie die chrome.alarms API verwenden möchten, deklarieren Sie die Berechtigung "alarms" im Manifest:
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
Konzepte und Verwendung
Um ein zuverlässiges Verhalten zu gewährleisten, ist es hilfreich, die Funktionsweise der API zu verstehen.
Ruhemodus
Wecker werden weiterhin ausgelöst, wenn sich ein Gerät im Ruhemodus befindet. Ein Wecker kann ein Gerät jedoch nicht aktivieren. Wenn das Gerät aktiviert wird, werden alle verpassten Wecker ausgelöst. Wiederholende Alarme werden höchstens einmal ausgelöst und dann mit dem angegebenen Zeitraum neu geplant. Dabei wird die Zeit berücksichtigt, die seit dem Aufwachen des Geräts vergangen ist, nicht jedoch die Zeit, die seit dem ursprünglichen Auslösen des Alarms vergangen ist.
Persistenz
Alarme bleiben in der Regel bestehen, bis eine Erweiterung aktualisiert wird. Dies ist jedoch nicht garantiert und Alarme werden möglicherweise gelöscht, wenn der Browser neu gestartet wird. Achten Sie daher darauf, dass sie jedes Mal vorhanden ist, wenn Ihr Service Worker gestartet wird. Beispiel:
async function checkAlarmState() {
const alarm = await chrome.alarms.get("my-alarm");
if (!alarm) {
await chrome.alarms.create("my-alarm", { periodInMinutes: 1 });
}
}
checkAlarmState();
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 im Service Worker ein Alarm 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 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
Attribute
-
name
String
Name dieses Weckers.
-
periodInMinutes
number optional
Wenn nicht null, ist der Wecker ein sich wiederholender Wecker und wird in
periodInMinutesMinuten wieder ausgelöst. -
scheduledTime
Zahl
Zeit, zu der dieser Alarm ausgelöst werden sollte, in Millisekunden seit dem Epoch-Zeitstempel (z.B.
Date.now() + n). Aus Leistungsgründen kann der Alarm um eine beliebige Zeit darüber hinaus verzögert worden sein.
AlarmCreateInfo
Attribute
-
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
periodInMinutesMinuten nach dem ursprünglichen Ereignis ausgelöst werden, das durchwhenoderdelayInMinutesangegeben wird. Wenn diese Option nicht festgelegt ist, wird der Alarm nur einmal ausgelöst. -
wann
number optional
Die Zeit, zu der der Wecker 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 Wecker mit dem angegebenen Namen.
Parameter
-
name
String optional
Der Name des zu löschenden Alarms. Die Standardeinstellung ist der leere String.
Ausgabe
-
Promise<boolean>
Chrome 91 und höher
clearAll()
chrome.alarms.clearAll(): Promise<boolean>
Löscht alle Wecker.
Ausgabe
-
Promise<boolean>
Chrome 91 und höher
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
): Promise<void>
Erstellt einen Wecker. Kurz vor den von alarmInfo angegebenen Zeiten wird das onAlarm-Ereignis 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 für die Häufigkeit, mit der 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
Beschreibt, wann der Wecker klingeln soll. Die Startzeit muss entweder mit
whenoderdelayInMinutesangegeben werden (aber nicht mit beiden). WennperiodInMinutesfestgelegt ist, wird der Alarm alleperiodInMinutesMinuten nach dem ursprünglichen Ereignis wiederholt. Wenn wederwhennochdelayInMinutesfür einen sich wiederholenden Alarm festgelegt ist, wirdperiodInMinutesals Standard fürdelayInMinutesverwendet.
Ausgabe
-
Promise<void>
Chrome 111 und höher
get()
chrome.alarms.get(
name?: string,
): Promise<Alarm | undefined>
Ruft Details zum angegebenen Wecker ab.
Parameter
-
name
String optional
Der Name des abzurufenden Weckers. Die Standardeinstellung ist der leere String.
Ausgabe
-
Promise<Alarm | undefined>
Chrome 91 und höher
Ausgabe
-
Promise<Alarm[]>
Chrome 91 und höher