Notification — Schnittstelle · JavaScript-Referenz

Signatur

interface Notification extends EventTarget

Beschreibung

Das Interface Notification gehört zur Notifications-API. Damit zeigt eine Webseite Benachrichtigungen an, die das Betriebssystem oder der Browser außerhalb des Seiteninhalts darstellt. Sie erscheinen auch dann, wenn der Tab im Hintergrund liegt oder das Fenster minimiert ist. Typische Einsatzfälle sind Chat-Nachrichten, Erinnerungen, fertige Hintergrundaufgaben oder Kalender-Termine.

Bevor eine Benachrichtigung erscheint, muss der Benutzer zustimmen. Den aktuellen Stand liest du über die statische Eigenschaft Notification.permission aus ("default", "granted" oder "denied"). Die Zustimmung holst du mit Notification.requestPermission() ein. Moderne Browser zeigen diesen Dialog nur nach einer Benutzeraktion (user activation) an, zum Beispiel nach einem Klick.

Eine Benachrichtigung erzeugst du mit new Notification(title, options). Die Instanz stellt schreibgeschützte Eigenschaften bereit, etwa title, body, icon, tag, data und silent. Mit der Methode close() schließt du sie wieder. Auf die Ereignisse click, show, close und error reagierst du mit addEventListener oder den Eigenschaften onclick, onshow, onclose und onerror.

In Service Workern ist der Konstruktor nicht erlaubt. Dort nutzt du ServiceWorkerRegistration.showNotification() und das Ereignis notificationclick. Auf Android-Chrome funktioniert nur dieser Weg. Für echte Push-Benachrichtigungen bei geschlossener Seite kombinierst du die API mit der Push-API.

Parameter

Name	Typ	Default	Beschreibung
$title Pflicht	string		Titel der Benachrichtigung (Konstruktor-Argument).
$options	object	{}	Optionales Konfigurationsobjekt für den Konstruktor.
$options.body	string	""	Haupttext unter dem Titel.
$options.icon	string		URL eines Symbolbilds.
$options.badge	string		URL eines kleinen, einfarbigen Symbols, v. a. für Mobilgeräte.
$options.tag	string	""	Gruppierungs-Kennung. Eine neue Benachrichtigung mit gleichem `tag` ersetzt die alte.
$options.renotify	boolean	false	Benachrichtigt beim Ersetzen per `tag` erneut (Ton/Vibration). Erfordert einen gesetzten `tag`.
$options.data	any	null	Beliebige strukturiert klonbare Daten, später über `notification.data` abrufbar.
$options.requireInteraction	boolean	false	Die Benachrichtigung bleibt sichtbar, bis der Benutzer sie schließt oder anklickt. Nicht überall unterstützt.
$options.silent	boolean\|null	null	Unterdrückt Ton und Vibration.
$options.lang	string	""	Sprache als BCP-47-Tag, z. B. `"de-DE"`.
$options.dir	"auto"\|"ltr"\|"rtl"	"auto"	Textrichtung.

Rückgabewert

Typ

Notification

Beschreibung

Der Konstruktor gibt eine neue Notification-Instanz zurück. Sie wird sofort angezeigt, wenn die Berechtigung erteilt ist. Ohne Berechtigung löst sie das Ereignis error aus.

Beispiele

Berechtigung nach Klick anfragen und Benachrichtigung zeigen

const button = document.querySelector('#notify-btn');

button.addEventListener('click', async () => {
  if (!('Notification' in window)) {
    console.log('Benachrichtigungen werden nicht unterstützt.');
    return;
  }

  let permission = Notification.permission;
  if (permission === 'default') {
    permission = await Notification.requestPermission();
  }

  if (permission === 'granted') {
    const n = new Notification('Download abgeschlossen', {
      body: 'bericht-2024.pdf wurde gespeichert.',
      icon: '/icons/download.png',
    });
    console.log(n.title);
  } else {
    console.log('Berechtigung:', permission);
  }
});

Download abgeschlossen

Klick-Ereignis behandeln und automatisch schließen

const showChatMessage = (sender, text, chatId) => {
  const n = new Notification(`Neue Nachricht von ${sender}`, {
    body: text,
    tag: `chat-${chatId}`, // ersetzt ältere Meldungen desselben Chats
    data: { chatId },
  });

  const handleClick = (event) => {
    event.preventDefault();
    window.focus();
    location.hash = `#chat/${n.data.chatId}`;
    n.close();
  };
  n.addEventListener('click', handleClick);

  n.onclose = () => {
    n.removeEventListener('click', handleClick);
    console.log('Benachrichtigung geschlossen');
  };

  // Nach 5 Sekunden automatisch schließen
  setTimeout(() => n.close(), 5000);
};

if (Notification.permission === 'granted') {
  showChatMessage('Anna', 'Treffen wir uns um 15 Uhr?', 42);
}

Benachrichtigung geschlossen

Über den Service Worker anzeigen (auch auf Android)

// Hauptskript
const notifyViaSW = async () => {
  const permission = await Notification.requestPermission();
  if (permission !== 'granted') return;

  const registration = await navigator.serviceWorker.ready;
  await registration.showNotification('Erinnerung', {
    body: 'Dein Termin beginnt in 10 Minuten.',
    tag: 'termin-17',
    data: { url: '/kalender/17' },
  });
};

// sw.js
self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  event.waitUntil(clients.openWindow(event.notification.data.url));
});

// Wichtig · Fallstricke

Nur in sicherem Kontext: Die API steht nur unter HTTPS oder localhost zur Verfügung. In Cross-Origin-iframes blockieren viele Browser die Berechtigungsanfrage.
Benutzeraktion nötig: Rufst du requestPermission() ohne Klick auf, etwa direkt beim Laden der Seite, ignorieren Chrome, Firefox und Safari den Aufruf oder zeigen nur einen dezenten Hinweis. Lehnt der Benutzer ab ("denied"), kannst du nicht erneut fragen. Nur der Benutzer selbst kann das in den Browsereinstellungen ändern.
Android/Chrome: Dort wirft new Notification() einen TypeError. Verwende stattdessen ServiceWorkerRegistration.showNotification(). In Service Workern steht der Konstruktor grundsätzlich nicht zur Verfügung.
iOS/iPadOS: Benachrichtigungen funktionieren erst ab Safari 16.4 und nur in Web-Apps, die zum Home-Bildschirm hinzugefügt wurden.
Alte Callback-Syntax: Ältere Safari-Versionen unterstützen requestPermission() nur mit Callback statt Promise.
Optionen wie requireInteraction, badge und renotify werden nicht überall unterstützt. Das Betriebssystem, etwa ein „Nicht stören“-Modus, kann Benachrichtigungen jederzeit unterdrücken.
Nutzererlebnis und Sicherheit: Zu viele Benachrichtigungen führen dazu, dass Benutzer die Berechtigung sperren. Zeige keine sensiblen Daten im body an, denn sie können auf dem Sperrbildschirm sichtbar sein. Auch wenn der Text nicht als HTML interpretiert wird, solltest du Inhalte von außen prüfen, bevor sie im Titel oder Text erscheinen.

Siehe auch

Location Navigation NotificationEvent Animation CSSAnimation CSSNestedDeclarations