Signatur
Beschreibung
Mit dem Konstruktor new Notification() zeigt eine Webseite eine native Benachrichtigung des Betriebssystems an, zum Beispiel für neue Chat-Nachrichten, abgeschlossene Uploads oder Erinnerungen. Die Benachrichtigung erscheint sofort beim Aufruf des Konstruktors. Eine eigene Methode zum Anzeigen gibt es nicht.
Vorher muss der Nutzer die Berechtigung erteilen. Das geschieht über Notification.requestPermission(), und diese Abfrage sollte nur als Reaktion auf eine Nutzeraktion (etwa einen Klick) ausgelöst werden. Ob die Berechtigung bereits vorliegt, zeigt die statische Eigenschaft Notification.permission mit den Werten "granted", "denied" oder "default". Ohne Berechtigung wird die Instanz zwar erzeugt, aber nichts angezeigt, und es wird ein error-Ereignis ausgelöst.
Die zurückgegebene Instanz ist ein EventTarget. Über die Ereignisse click, show, close und error kann man auf Nutzerinteraktionen reagieren. Mit close() entfernt man die Benachrichtigung per Code. Über die Option tag lassen sich ältere Benachrichtigungen desselben Themas ersetzen, statt sie zu stapeln.
In Service Workern und in Chrome für Android ist der Konstruktor nicht verfügbar und wirft dort einen TypeError. Stattdessen verwendet man ServiceWorkerRegistration.showNotification(). Diese Methode ist auch die Grundlage für Push-Benachrichtigungen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $title Pflicht | string | Titel der Benachrichtigung, der fett oben angezeigt wird. | |
| $options | object | {} | Konfigurationsobjekt mit optionalen Feldern:
|
Rückgabewert
Notification-Instanz. Sie wird sofort angezeigt, sofern die Berechtigung vorliegt.Beispiele
Berechtigung anfragen und Benachrichtigung anzeigen
const button = document.querySelector('#notify');
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') {
new Notification('Upload abgeschlossen', {
body: 'bericht.pdf wurde erfolgreich hochgeladen.',
icon: '/img/upload-icon.png'
});
} else {
console.log('Berechtigung verweigert:', permission);
}
});Auf Klick reagieren und automatisch schließen
const showChatMessage = (sender, text, chatId) => {
const notification = new Notification(`Neue Nachricht von ${sender}`, {
body: text,
tag: `chat-${chatId}`, // ersetzt ältere Meldungen desselben Chats
data: { chatId }
});
notification.addEventListener('click', () => {
window.focus();
location.hash = `#chat/${notification.data.chatId}`;
notification.close();
});
// Nach 8 Sekunden automatisch ausblenden
setTimeout(() => notification.close(), 8000);
};
if (Notification.permission === 'granted') {
showChatMessage('Anna', 'Treffen wir uns um 15 Uhr?', 42);
}Nur benachrichtigen, wenn der Tab im Hintergrund ist
const notifyIfHidden = (title, body) => {
if (document.visibilityState === 'visible') {
console.log('Tab ist sichtbar – keine Benachrichtigung nötig.');
return null;
}
if (Notification.permission !== 'granted') return null;
const n = new Notification(title, { body, silent: true });
n.onerror = () => console.error('Benachrichtigung konnte nicht angezeigt werden.');
return n;
};
notifyIfHidden('Build fertig', 'Alle 128 Tests bestanden.');Fallback über den Service Worker (z. B. Chrome für Android)
const notify = async (title, options = {}) => {
try {
return new Notification(title, options);
} catch (err) {
// TypeError: Konstruktor hier nicht erlaubt
const registration = await navigator.serviceWorker.ready;
await registration.showNotification(title, options);
return null;
}
};
if (Notification.permission === 'granted') {
await notify('Erinnerung', { body: 'Termin in 10 Minuten.' });
}// Wichtig · Fallstricke
- Nur im sicheren Kontext: Die API funktioniert nur über HTTPS (oder
localhost). Viele Browser verweigern die Berechtigungsabfrage, wenn sie nicht durch eine Nutzeraktion ausgelöst wurde. Firefox und Safari blockieren solche Abfragen, Chrome zeigt sie nur unauffällig an. - Kein Konstruktor in Service Workern und Chrome für Android: Dort wirft
new Notification()einenTypeError. StattdessenServiceWorkerRegistration.showNotification()verwenden. - Ohne Berechtigung: Es wird keine Ausnahme geworfen. Die Instanz entsteht trotzdem, wird aber nicht angezeigt, und es feuert ein
error-Ereignis. Deshalb vorherNotification.permissionprüfen. - Hat der Nutzer abgelehnt (
"denied"), kann die Seite nicht erneut fragen. Nur der Nutzer selbst kann das in den Browsereinstellungen ändern. - Uneinheitliche Unterstützung der Optionen:
image,vibrate,badgeundrequireInteractionwerden nicht von allen Browsern und Betriebssystemen dargestellt. Den Nicht-Stören-Modus des Betriebssystems kann die Seite nicht umgehen. - Safari unterstützt auf iOS/iPadOS Benachrichtigungen erst ab Version 16.4 und nur für Web-Apps, die zum Home-Bildschirm hinzugefügt wurden.
- Sparsam einsetzen: Zu viele Benachrichtigungen führen schnell dazu, dass Nutzer die Berechtigung dauerhaft entziehen.