Navigator.clearAppBadge() — Methode · JavaScript-Referenz

Signatur

Navigator.prototype.clearAppBadge()

Beschreibung

navigator.clearAppBadge() gehört zur Badging API und entfernt ein vorher mit navigator.setAppBadge() gesetztes Badge vom App-Icon, etwa in der Taskleiste, im Dock oder auf dem Homescreen. Das Ergebnis ist dasselbe wie bei navigator.setAppBadge(0).

Typischerweise rufst du die Methode auf, wenn ein Zustand, den das Badge anzeigen soll, erledigt ist. Beispiele sind gelesene Nachrichten, abgearbeitete Aufgaben oder der Moment, in dem die Nutzerin die App wieder in den Vordergrund holt. Die Methode gibt es auch in Web Workern (WorkerNavigator). So kannst du das Badge zum Beispiel direkt aus einem Service Worker heraus löschen, wenn eine Push-Nachricht eingeht.

Das Badge wird nur angezeigt, wenn die Seite als Progressive Web App installiert ist und in einem sicheren Kontext (HTTPS) läuft. In einem normalen Browser-Tab passiert beim Aufruf sichtbar nichts. Das Promise wird trotzdem meist ohne Fehler erfüllt.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald das Badge entfernt wurde. Wird abgelehnt (z. B. mit NotAllowedError), wenn der Browser das Badge nicht löschen darf, oder mit InvalidStateError, wenn das Dokument nicht vollständig aktiv ist.

Beispiele

Badge sicher löschen mit Feature-Erkennung

const resetBadge = async () => {
  if (!('clearAppBadge' in navigator)) {
    console.log('Badging API wird nicht unterstützt');
    return;
  }
  try {
    await navigator.clearAppBadge();
    console.log('Badge entfernt');
  } catch (err) {
    console.error('Badge konnte nicht entfernt werden:', err.name);
  }
};

resetBadge();

Badge entfernt

Badge löschen, sobald die App sichtbar wird

let unread = 5;
navigator.setAppBadge?.(unread);

document.addEventListener('visibilitychange', async () => {
  if (document.visibilityState === 'visible') {
    unread = 0;
    // Nutzer sieht die Nachrichten jetzt – Badge zurücksetzen
    await navigator.clearAppBadge?.();
    console.log('Ungelesene Nachrichten zurückgesetzt');
  }
});

Ungelesene Nachrichten zurückgesetzt

Zähler-Helfer: setAppBadge oder clearAppBadge

const updateBadge = async (count) => {
  if (!('setAppBadge' in navigator)) return;
  if (count > 0) {
    await navigator.setAppBadge(count);
  } else {
    await navigator.clearAppBadge();
  }
  console.log(`Badge-Stand: ${count}`);
};

await updateBadge(3);
await updateBadge(0);

Badge-Stand: 3 Badge-Stand: 0

Im Service Worker nach Klick auf eine Benachrichtigung

// service-worker.js
self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  event.waitUntil(
    (async () => {
      if ('clearAppBadge' in self.navigator) {
        await self.navigator.clearAppBadge();
      }
      await self.clients.openWindow('/inbox');
    })()
  );
});

// Wichtig · Fallstricke

Browser-Unterstützung: Chrome/Edge ab 81 auf Windows und macOS, ChromeOS; Safari ab 16.4 nur für Web-Apps, die zum Home-Bildschirm bzw. Dock hinzugefügt wurden. Firefox unterstützt die API nicht. Prüfe deshalb immer vorher mit 'clearAppBadge' in navigator.
Nur bei installierten PWAs sichtbar: In einem normalen Tab hat der Aufruf keine sichtbare Wirkung. Das ist kein Fehler.
Sicherer Kontext nötig: Die Methode gibt es nur unter HTTPS (oder localhost).
Berechtigungen: Unter iOS/iPadOS muss für die Web-App die Benachrichtigungs-Berechtigung erteilt sein, sonst werden Badges nicht angezeigt.
clearAppBadge() entspricht setAppBadge(0). setAppBadge() ohne Argument setzt dagegen einen Markierungspunkt ohne Zahl.
Nicht verwechseln mit dem Dokument-Badge (setClientBadge/clearClientBadge), das nur als Entwurf existierte und von keinem Browser ausgeliefert wird.
Das Promise immer mit await/catch behandeln, damit keine unbehandelten Ablehnungen entstehen.

Siehe auch

Navigator.setAppBadge() Navigator WorkerNavigator Notification Navigator.taintEnabled()