Event.cancelBubble — Eigenschaft · JavaScript-Referenz

Signatur

Event.cancelBubble

Beschreibung

Event.cancelBubble ist ein historischer Alias für Event.prototype.stopPropagation(). Die Eigenschaft stammt ursprünglich aus dem Internet Explorer. Sie wurde später in den DOM-Standard aufgenommen, damit bestehende Webseiten weiter funktionieren. Setzt man sie während der Verarbeitung eines Events auf true, wird das Event nicht mehr an weitere Knoten weitergereicht. Das gilt in der Bubbling-Phase und auch in der Capturing-Phase.

Beim Lesen liefert cancelBubble den Wert true, wenn für das Event bereits stopPropagation() oder stopImmediatePropagation() aufgerufen wurde, sonst false. Das Setzen auf false hat laut Spezifikation keine Wirkung: Einmal gestoppt, bleibt das Event gestoppt.

In neuem Code sollte man immer event.stopPropagation() verwenden. cancelBubble begegnet einem heute vor allem in älterem Code, der noch für den Internet Explorer geschrieben wurde. Ohne Weiteres entfernen sollte man solche Stellen nicht. Die Browser unterstützen sie weiterhin, sie gelten aber als veraltet.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn die Weitergabe des Events bereits gestoppt wurde, sonst false. Schreibbar: Mit true wird die Weitergabe gestoppt, false wird ignoriert.

Beispiele

Bubbling stoppen (veraltete Schreibweise)

// HTML: <div id="aussen"><button id="knopf">Klick</button></div>
const aussen = document.getElementById('aussen');
const knopf = document.getElementById('knopf');

aussen.addEventListener('click', () => console.log('Container geklickt'));

knopf.addEventListener('click', (event) => {
  console.log('Button geklickt');
  event.cancelBubble = true; // entspricht event.stopPropagation()
});

Button geklickt

Moderne Entsprechung mit stopPropagation()

knopf.addEventListener('click', (event) => {
  console.log('Button geklickt');
  event.stopPropagation(); // empfohlen
});

Button geklickt

Status lesen und Zurücksetzen wirkungslos

const event = new Event('test', { bubbles: true });
console.log(event.cancelBubble);

event.stopPropagation();
console.log(event.cancelBubble);

event.cancelBubble = false; // hat keine Wirkung
console.log(event.cancelBubble);

false true true

Kompatibilitäts-Hilfsfunktion für Altcode

const stoppeWeitergabe = (event) => {
  if (typeof event.stopPropagation === 'function') {
    event.stopPropagation();
  } else {
    event.cancelBubble = true; // Fallback für sehr alte IE-Versionen
  }
};

document.querySelector('a')?.addEventListener('click', stoppeWeitergabe);

// Wichtig · Fallstricke

Veraltet: Verwende in neuem Code event.stopPropagation(). cancelBubble ist nur aus Gründen der Rückwärtskompatibilität spezifiziert.
Das Setzen auf false hebt ein Stoppen nicht auf. Dieses Verhalten schreibt die Spezifikation so vor.
Der Name ist irreführend: Die Eigenschaft stoppt nicht nur das Bubbling, sondern die Weitergabe in allen Phasen, also auch beim Capturing.
cancelBubble verhindert nicht die Standardaktion des Browsers, etwa das Folgen eines Links. Dafür ist event.preventDefault() zuständig.
Wie bei stopPropagation() werden die übrigen Listener auf demselben Element trotzdem ausgeführt. Um auch diese zu unterbinden, verwendet man stopImmediatePropagation().
Unterstützt wird die Eigenschaft von allen aktuellen Browsern (Chrome, Firefox, Safari, Edge). In sehr altem Firefox (vor Version 53) fehlte sie.

Siehe auch

Event.prototype.stopPropagation() Event.prototype.stopImmediatePropagation() Event.prototype.preventDefault() Event.bubbles Event.returnValue Event Event.srcElement