Element.setCapture() — Methode · JavaScript-Referenz

Signatur

Element.prototype.setCapture(retargetToElement)

Beschreibung

setCapture() wird typischerweise in einem mousedown-Handler aufgerufen. Danach erhält das Element alle folgenden Mausereignisse wie mousemove und mouseup, auch wenn sich der Mauszeiger längst außerhalb des Elements oder sogar außerhalb des Fensters befindet. Das war früher die übliche Methode für Drag-Interaktionen, etwa bei Schiebereglern, Fenster-Griffen oder Zeichenflächen.

Die Umleitung endet automatisch, sobald die Maustaste losgelassen wird. Manuell beenden lässt sie sich mit document.releaseCapture(). Beim Beenden wird ein losecapture-Ereignis ausgelöst. Hat der Parameter retargetToElement den Wert true, wird bei allen Ereignissen event.target auf das erfassende Element gesetzt. Bei false können Ereignisse auch Kindelemente als Ziel haben.

Für neuen Code nicht verwenden. Der Standard-Ersatz ist Element.setPointerCapture(pointerId) aus der Pointer-Events-API. Diese API funktioniert in allen aktuellen Browsern und unterstützt Maus, Stift und Touch gleichermaßen. Wenn nur Maus-Drag nötig ist, gibt es noch eine zweite Möglichkeit: Die mousemove- und mouseup-Listener während des Ziehens an document oder window hängen.

Parameter

Name	Typ	Default	Beschreibung
$retargetToElement	boolean	false	Bei `true` wird `event.target` aller umgeleiteten Ereignisse auf dieses Element gesetzt. Bei `false` können Ereignisse weiterhin auf Nachfahren des Elements zielen.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Klassisch: Ziehen mit setCapture und Rückfallebene

const handle = document.querySelector('#slider-handle');

const onMove = (e) => {
  handle.style.left = `${e.clientX}px`;
};

const onUp = () => {
  // Ohne setCapture hingen die Listener an document, also dort entfernen
  document.removeEventListener('mousemove', onMove);
  document.removeEventListener('mouseup', onUp);
  handle.removeEventListener('mousemove', onMove);
  handle.removeEventListener('mouseup', onUp);
  console.log('Ziehen beendet');
};

handle.addEventListener('mousedown', (e) => {
  if (typeof handle.setCapture === 'function') {
    handle.setCapture(true); // alle Mausereignisse gehen jetzt an handle
    handle.addEventListener('mousemove', onMove);
    handle.addEventListener('mouseup', onUp);
  } else {
    // Rückfallebene für alle anderen Browser
    document.addEventListener('mousemove', onMove);
    document.addEventListener('mouseup', onUp);
  }
  e.preventDefault();
});

Ziehen beendet

Umleitung vorzeitig beenden und auf losecapture reagieren

const canvas = document.querySelector('#zeichenflaeche');

canvas.addEventListener('losecapture', () => {
  console.log('Maus-Umleitung beendet');
});

canvas.addEventListener('mousedown', () => {
  canvas.setCapture?.();
  // Nach 2 Sekunden abbrechen, z. B. als Zeitlimit
  setTimeout(() => document.releaseCapture?.(), 2000);
});

Maus-Umleitung beendet

Moderner Ersatz: setPointerCapture

const handle = document.querySelector('#slider-handle');

handle.addEventListener('pointerdown', (e) => {
  handle.setPointerCapture(e.pointerId);
});

handle.addEventListener('pointermove', (e) => {
  if (handle.hasPointerCapture(e.pointerId)) {
    handle.style.left = `${e.clientX}px`;
  }
});

handle.addEventListener('lostpointercapture', () => {
  console.log('Pointer-Umleitung beendet');
});

Pointer-Umleitung beendet

// Wichtig · Fallstricke

Nicht standardisiert und veraltet: Nur Firefox und der alte Internet Explorer haben die Methode. Chrome, Edge (Chromium) und Safari kennen sie nicht. Der Aufruf wirft dort einen TypeError, deshalb vorher mit typeof el.setCapture === 'function' oder optionalem Aufruf (el.setCapture?.()) prüfen.
Die Methode wirkt nur, wenn sie während eines mousedown-Ereignisses aufgerufen wird. Später aufgerufen, hat sie in Firefox keine Wirkung.
Es kann immer nur ein Element die Maus erfassen. Ein neuer Aufruf auf einem anderen Element beendet die bestehende Umleitung.
Touch- und Stifteingaben werden nicht abgedeckt. Für geräteübergreifende Interaktionen setPointerCapture() verwenden, das in allen aktuellen Browsern verfügbar ist.
Nicht mit der Pointer Lock API (requestPointerLock()) verwechseln: Diese blendet den Mauszeiger aus und liefert nur relative Bewegungen.

Siehe auch

Document.releaseCapture() Element.setPointerCapture() Element.releasePointerCapture() Element.hasPointerCapture() Element.requestPointerLock() new ImageCapture()