Document.releaseCapture() — Methode · JavaScript-Referenz

Signatur

Document.prototype.releaseCapture()

Beschreibung

document.releaseCapture() ist das Gegenstück zu Element.setCapture(). Hat ein Element mit setCapture() die Mauserfassung übernommen, bekommt es alle Mausereignisse (mousemove, mouseup usw.), auch wenn der Mauszeiger das Element oder sogar das Browserfenster verlässt. Mit releaseCapture() wird dieser Zustand beendet, und die Ereignisse gehen danach wieder an das Element, das tatsächlich unter dem Mauszeiger liegt.

Gebraucht wurde das früher vor allem für Ziehvorgänge: Schieberegler, verschiebbare Fenster, Größenänderung von Bereichen oder Zeichenflächen. Dort sollte ein Ziehvorgang nicht abbrechen, nur weil der Nutzer die Maus zu schnell bewegt und das Element dabei verlässt.

Die Methode hat keine Parameter und gibt nichts zurück. Ist gerade keine Erfassung aktiv, passiert beim Aufruf nichts. Loslassen der Maustaste beendet die Erfassung übrigens automatisch – ein expliziter Aufruf ist nur nötig, wenn man sie vorher beenden will, etwa bei Escape oder einem Fehler.

Für neuen Code solltest du stattdessen die standardisierte Pointer-Capture-API der Pointer Events verwenden: Element.setPointerCapture(pointerId) und Element.releasePointerCapture(pointerId). Sie funktioniert in allen modernen Browsern und deckt auch Touch- und Stifteingaben ab.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Erfassung bei Escape vorzeitig beenden (Firefox)

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

handle.addEventListener('mousedown', (event) => {
  // true = Ereignisse direkt an dieses Element leiten (retargetToElement)
  handle.setCapture?.(true);
  console.log('Erfassung aktiv');
});

document.addEventListener('keydown', (event) => {
  if (event.key === 'Escape') {
    // Ziehvorgang abbrechen – Erfassung sofort freigeben
    document.releaseCapture?.();
    console.log('Erfassung per Escape beendet');
  }
});

Erfassung aktiv Erfassung per Escape beendet

Ziehbarer Schieberegler mit Feature-Erkennung und Fallback

const thumb = document.querySelector('.slider-thumb');
const track = document.querySelector('.slider-track');
const supportsLegacyCapture = typeof document.releaseCapture === 'function';

const updatePosition = (clientX) => {
  const rect = track.getBoundingClientRect();
  const ratio = Math.min(Math.max((clientX - rect.left) / rect.width, 0), 1);
  thumb.style.left = `${ratio * 100}%`;
  return Math.round(ratio * 100);
};

const onMove = (e) => updatePosition(e.clientX);

const onUp = (e) => {
  const value = updatePosition(e.clientX);
  if (supportsLegacyCapture) document.releaseCapture();
  thumb.removeEventListener('mousemove', onMove);
  thumb.removeEventListener('mouseup', onUp);
  console.log(`Endwert: ${value}`);
};

thumb.addEventListener('mousedown', () => {
  if (supportsLegacyCapture) thumb.setCapture(true);
  thumb.addEventListener('mousemove', onMove);
  thumb.addEventListener('mouseup', onUp);
});

Endwert: 73

Empfohlen: Standard-Alternative mit Pointer Capture

const thumb = document.querySelector('.slider-thumb');

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

thumb.addEventListener('pointermove', (e) => {
  if (thumb.hasPointerCapture(e.pointerId)) {
    console.log('Ziehe bei x =', e.clientX);
  }
});

thumb.addEventListener('pointerup', (e) => {
  // Entspricht document.releaseCapture(), aber standardisiert
  thumb.releasePointerCapture(e.pointerId);
  console.log('Pointer freigegeben');
});

Ziehe bei x = 214 Pointer freigegeben

// Wichtig · Fallstricke

Nicht standardisiert und veraltet: Die Methode gibt es nur in Firefox (Gecko). Chrome, Edge und Safari kennen sie nicht – ein direkter Aufruf wirft dort TypeError: document.releaseCapture is not a function. Prüfe deshalb immer vorher, ob sie vorhanden ist, z. B. mit document.releaseCapture?.().
Der alte Internet Explorer hatte eine gleichnamige Methode am Element (element.releaseCapture()), nicht am Dokument. Sie verhielt sich außerdem teilweise anders.
Die Erfassung endet automatisch, wenn die Maustaste losgelassen wird. Ein zusätzlicher Aufruf schadet nicht, ist aber oft überflüssig.
setCapture() wirkt nur, wenn es während eines mousedown-Ereignisses aufgerufen wird. Ohne aktive Erfassung macht releaseCapture() nichts.
Für plattformübergreifenden Code, der auch Touch- und Stifteingaben abdeckt, nimm Element.setPointerCapture() / Element.releasePointerCapture(). Diese API wird in allen modernen Browsern unterstützt.

Siehe auch

Element.setCapture() Element.setPointerCapture() Element.releasePointerCapture() Element.hasPointerCapture() PointerEvent Document DOMImplementation.hasFeature()