Signatur
Beschreibung
clearAppBadge() gehört zur Badging API und ist über navigator innerhalb eines Workers erreichbar, meist in einem Service Worker. Die Methode entfernt ein zuvor mit setAppBadge() gesetztes Abzeichen vom Symbol der installierten Progressive Web App (PWA), etwa in der Taskleiste, im Dock oder auf dem Startbildschirm.
Typischer Fall: Ein Service Worker bekommt Push-Nachrichten und erhöht dabei den Zähler ungelesener Elemente auf dem App-Symbol. Hat der Nutzer die Nachrichten gelesen, z. B. nach einem Klick auf die Benachrichtigung oder nach einem Sync mit dem Server, entfernt clearAppBadge() das Abzeichen wieder, ohne dass ein Fenster der App offen sein muss.
Der Aufruf hat dieselbe Wirkung wie navigator.setAppBadge(0). Er gibt ein Promise zurück, das sich erfüllt, sobald das Abzeichen entfernt wurde. Auf Plattformen ohne Unterstützung oder in nicht erlaubten Kontexten wird das Promise abgelehnt.
Rückgabewert
Promise, das sich mit undefined erfüllt, sobald das Abzeichen entfernt wurde. Es wird mit einer DOMException abgelehnt, zum Beispiel NotAllowedError, wenn der Kontext das Setzen oder Entfernen von Abzeichen nicht erlaubt.Beispiele
Abzeichen im Service Worker entfernen
// sw.js
const resetBadge = async () => {
if (!('clearAppBadge' in navigator)) {
console.log('Badging API nicht verfügbar');
return;
}
try {
await navigator.clearAppBadge();
console.log('Badge entfernt');
} catch (err) {
console.error('Badge konnte nicht entfernt werden:', err.name);
}
};
resetBadge();Badge beim Klick auf eine Benachrichtigung zurücksetzen
// sw.js
self.addEventListener('notificationclick', (event) => {
event.notification.close();
event.waitUntil((async () => {
// Nutzer hat reagiert, ungelesen-Zähler zurücksetzen
if ('clearAppBadge' in navigator) {
await navigator.clearAppBadge();
}
const clientList = await clients.matchAll({ type: 'window', includeUncontrolled: true });
if (clientList.length > 0) {
return clientList[0].focus();
}
return clients.openWindow('/posteingang');
})());
});Zähler per Push setzen, bei 0 entfernen
// sw.js
self.addEventListener('push', (event) => {
const data = event.data?.json() ?? { unread: 0 };
event.waitUntil((async () => {
if (!('setAppBadge' in navigator)) return;
if (data.unread > 0) {
await navigator.setAppBadge(data.unread);
} else {
await navigator.clearAppBadge();
}
// Hinweis: Chrome verlangt bei Push in der Regel eine sichtbare Benachrichtigung
await self.registration.showNotification('Posteingang', {
body: data.unread > 0 ? `${data.unread} ungelesene Nachrichten` : 'Alles gelesen'
});
})());
});// Wichtig · Fallstricke
- Browser-Unterstützung: Chromium-Browser (Chrome, Edge) unter Windows und macOS sowie Safari 16.4+ unterstützen die Methode. Firefox unterstützt sie nicht. Prüfe deshalb immer mit
'clearAppBadge' in navigator, ob sie vorhanden ist. - Das Abzeichen ist nur bei einer installierten Web-App sichtbar. Unter iOS/iPadOS muss die App zum Home-Bildschirm hinzugefügt sein, und dort ist zusätzlich die Berechtigung für Benachrichtigungen nötig (
Notification.requestPermission()). - Die Methode funktioniert nur in einem sicheren Kontext (HTTPS oder
localhost). clearAppBadge()hat dieselbe Wirkung wiesetAppBadge(0).- In Service-Worker-Ereignissen den Aufruf in
event.waitUntil()einbetten. Sonst kann der Worker beendet werden, bevor das Promise erfüllt ist. - Auf manchen Plattformen, etwa bestimmten Android-Launchern, zeigt das Betriebssystem Abzeichen anders an oder ignoriert sie. Das Promise kann sich trotzdem erfüllen.