Notification.badge — Eigenschaft · JavaScript-Referenz

Signatur

Notification.badge

Beschreibung

Die schreibgeschützte Eigenschaft badge der Notification-Schnittstelle gibt als Zeichenkette die URL eines Bildes zurück. Dieses Bild steht für die Benachrichtigung, wenn nicht genug Platz ist, um sie vollständig anzuzeigen, zum Beispiel in der Android-Statusleiste. Das Badge ist in der Regel ein kleines, einfarbiges Symbol (etwa ein Logo als Silhouette), das vom Betriebssystem eingefärbt wird.

Den Wert legst du beim Erzeugen der Benachrichtigung über die Option badge fest, entweder im Konstruktor new Notification(title, options) oder, was häufiger vorkommt, in ServiceWorkerRegistration.prototype.showNotification(title, options). Später lässt er sich nur noch lesen. Relative URLs werden aufgelöst, deshalb gibt die Eigenschaft eine absolute URL zurück. Wurde kein Badge angegeben, ist der Wert eine leere Zeichenkette.

Ausgewertet wird das Badge vor allem auf Mobilgeräten (Chrome für Android). Desktop-Browser zeigen es meist gar nicht an. Die Eigenschaft ist deshalb eher ein Zusatz für Progressive Web Apps mit Push-Benachrichtigungen als ein Muss.

Rückgabewert

Typ

string

Beschreibung

Absolute URL des Badge-Bildes oder eine leere Zeichenkette "", wenn kein Badge gesetzt wurde.

Beispiele

Badge beim Erzeugen setzen und auslesen

const zeigeHinweis = async () => {
  const erlaubnis = await Notification.requestPermission();
  if (erlaubnis !== 'granted') return;

  const n = new Notification('Neue Nachricht', {
    body: 'Anna hat dir geschrieben.',
    icon: '/img/icon-192.png',
    badge: '/img/badge-72.png'
  });

  console.log(n.badge);
};

zeigeHinweis();

https://example.com/img/badge-72.png

Push-Benachrichtigung im Service Worker mit Badge

// sw.js
self.addEventListener('push', (event) => {
  const daten = event.data?.json() ?? { titel: 'Update', text: 'Es gibt Neuigkeiten.' };

  event.waitUntil(
    self.registration.showNotification(daten.titel, {
      body: daten.text,
      icon: '/img/icon-192.png',
      badge: '/img/badge-mono-96.png', // einfarbig, transparent
      tag: 'news'
    })
  );
});

Aktive Benachrichtigungen auf ihr Badge prüfen

const pruefeBadges = async () => {
  const reg = await navigator.serviceWorker.ready;
  const liste = await reg.getNotifications();

  for (const n of liste) {
    console.log(`${n.title}: ${n.badge || '(kein Badge)'}`);
  }
};

pruefeBadges();

Update: https://example.com/img/badge-mono-96.png

Feature-Erkennung vor der Nutzung

const badgeUnterstuetzt = 'Notification' in window && 'badge' in Notification.prototype;
console.log(badgeUnterstuetzt ? 'Badge wird unterstützt' : 'Badge wird ignoriert');

Badge wird unterstützt

// Wichtig · Fallstricke

Browser-Unterstützung: Nur Chromium-Browser (Chrome, Edge, Opera, Samsung Internet) werten die Eigenschaft aus. Firefox und Safari kennen sie nicht. Dort ist n.badge undefined und die Option wird stillschweigend ignoriert.
Nur lesbar: Eine Zuweisung wie n.badge = '...' hat keine Wirkung. Um das Badge zu ändern, erzeugst du eine neue Benachrichtigung, am besten mit demselben tag, damit die alte ersetzt wird.
Bildgestaltung: Android nutzt nur den Alphakanal und färbt das Bild selbst ein. Farbige Bilder ohne Transparenz erscheinen daher als weißes oder graues Quadrat. Empfohlen sind etwa 96×96 Pixel, einfarbig und mit transparentem Hintergrund.
Nicht verwechseln: badge ist nicht dasselbe wie icon (großes Bild in der Benachrichtigung) oder die App-Badging-API navigator.setAppBadge() (Zähler am App-Symbol).
Benachrichtigungen setzen einen sicheren Kontext (HTTPS) und die Zustimmung der Nutzerin oder des Nutzers voraus. In Chrome für Android funktioniert new Notification() nicht; dort ist showNotification() im Service Worker Pflicht.

Siehe auch

Notification Notification.icon Notification.image NetworkInformation.saveData Notification.body