Event.cancelable — Eigenschaft · JavaScript-Referenz

Signatur

Event.cancelable

Beschreibung

Die schreibgeschützte Eigenschaft cancelable der Event-Schnittstelle zeigt an, ob sich ein Ereignis abbrechen lässt. Bei true kann ein Listener mit event.preventDefault() die Standardaktion des Browsers verhindern, zum Beispiel das Absenden eines Formulars, das Öffnen eines Links oder das Scrollen bei wheel- oder touchmove-Ereignissen.

Ob ein Ereignis abbrechbar ist, legt derjenige fest, der es erzeugt. Bei nativen Ereignissen entscheidet das die Spezifikation: click, submit und keydown sind abbrechbar, load, scroll und focus nicht. Bei eigenen Ereignissen bestimmt die Option cancelable im Konstruktor von Event oder CustomEvent den Wert. Standardmäßig ist er false.

In der Praxis prüft man cancelable vor dem Aufruf von preventDefault(). Das ist vor allem bei Ereignissen wichtig, die der Browser nur in manchen Situationen abbrechen lässt, etwa touchmove während eines laufenden Scrollvorgangs. Ist die Eigenschaft false, bewirkt preventDefault() nichts. Manche Browser geben dann eine Warnung in der Konsole aus.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Ereignis abgebrochen werden kann, sonst false.

Beispiele

Scrollen per Mausrad nur verhindern, wenn es erlaubt ist

const box = document.querySelector('#zoom-box');

// passive: false ist nötig, sonst lässt sich wheel nicht abbrechen
box.addEventListener('wheel', (event) => {
  if (event.cancelable) {
    event.preventDefault();
    console.log('Scrollen verhindert, stattdessen Zoom');
  } else {
    console.log('Ereignis nicht abbrechbar');
  }
}, { passive: false });

Scrollen verhindert, stattdessen Zoom

Eigenes, abbrechbares Ereignis auslösen

const dialog = document.createElement('div');

dialog.addEventListener('beforeclose', (event) => {
  console.log('cancelable:', event.cancelable);
  // Schließen verhindern, z. B. bei ungespeicherten Änderungen
  event.preventDefault();
});

const closeEvent = new CustomEvent('beforeclose', { cancelable: true });
// dispatchEvent gibt false zurück, wenn preventDefault() aufgerufen wurde
const darfSchliessen = dialog.dispatchEvent(closeEvent);
console.log('Schließen erlaubt:', darfSchliessen);

cancelable: true Schließen erlaubt: false

Standardwert bei eigenen Ereignissen

const e1 = new Event('ping');
const e2 = new Event('ping', { cancelable: true });

e1.preventDefault(); // bewirkt nichts
e2.preventDefault();

console.log(e1.cancelable, e1.defaultPrevented);
console.log(e2.cancelable, e2.defaultPrevented);

false false true true

Native Ereignisse vergleichen

document.addEventListener('click', (e) => console.log('click:', e.cancelable));
window.addEventListener('scroll', (e) => console.log('scroll:', e.cancelable));

click: true scroll: false

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie event.cancelable = true wird im nicht-strikten Modus stillschweigend ignoriert und löst im strikten Modus einen TypeError aus. Der Wert lässt sich nur beim Erzeugen über die Konstruktor-Option festlegen.
Passive Listener: In Listenern mit { passive: true } wird preventDefault() ignoriert, auch wenn cancelable den Wert true hat. Chrome und Firefox registrieren touchstart, touchmove und wheel auf window, document und body standardmäßig als passiv.
Nicht mit defaultPrevented verwechseln: cancelable sagt, ob abgebrochen werden kann. defaultPrevented sagt, ob tatsächlich abgebrochen wurde.
Wert kann sich je nach Situation ändern: Bei Touch-Ereignissen setzt der Browser cancelable während eines laufenden Scrollvorgangs auf false. Deshalb sollte man den Wert jedes Mal prüfen, statt sich auf den Ereignistyp zu verlassen.
Nicht mit stopPropagation() verwechseln: stopPropagation() hält die Weitergabe des Ereignisses an andere Elemente an und funktioniert unabhängig von cancelable.
Die Eigenschaft wird von allen modernen Browsern seit Langem unterstützt.

Siehe auch

Event.preventDefault() Event.defaultPrevented Event.bubbles Event.stopPropagation() Event.cancelBubble