Element.releasePointerCapture() — Methode · JavaScript-Referenz

Signatur

Element.prototype.releasePointerCapture(pointerId)

Beschreibung

Mit releasePointerCapture() wird die Pointer-Capture (Zeiger-Erfassung) für einen bestimmten Zeiger beendet. Solange ein Element einen Zeiger erfasst hat, werden alle Pointer-Events dieses Zeigers (pointermove, pointerup usw.) an dieses Element geleitet, auch wenn der Zeiger sich gar nicht mehr über dem Element befindet. Nach dem Freigeben werden die Events wieder ganz normal per Hit-Testing an das Element unter dem Zeiger geschickt.

Normalerweise gibt der Browser die Erfassung bei pointerup oder pointercancel automatisch frei. Einen expliziten Aufruf braucht man deshalb vor allem dann, wenn eine Drag- oder Zeichen-Interaktion vorzeitig enden soll, etwa bei Erreichen eines Grenzwerts, bei Abbruch per Escape-Taste oder wenn ein Element die Erfassung an ein anderes übergeben soll.

Nach der Freigabe feuert der Browser am Element das Event lostpointercapture. Ob ein Element einen Zeiger gerade erfasst hat, lässt sich mit hasPointerCapture() prüfen.

Parameter

Name	Typ	Default	Beschreibung
$pointerId Pflicht	number		Die Kennung des Zeigers, dessen Erfassung freigegeben werden soll, meist aus `event.pointerId` eines `PointerEvent`.

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück.

Beispiele

Drag-Slider mit Capture setzen und freigeben

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

thumb.addEventListener('pointerdown', (event) => {
  thumb.setPointerCapture(event.pointerId);
  thumb.addEventListener('pointermove', onMove);
});

const onMove = (event) => {
  thumb.style.transform = `translateX(${event.clientX}px)`;
};

thumb.addEventListener('pointerup', (event) => {
  thumb.removeEventListener('pointermove', onMove);
  // Wird hier ohnehin automatisch freigegeben, ein expliziter Aufruf schadet aber nicht
  thumb.releasePointerCapture(event.pointerId);
});

Vorzeitiger Abbruch beim Überschreiten eines Grenzwerts

const handle = document.querySelector('#handle');
let startX = 0;

handle.addEventListener('pointerdown', (event) => {
  startX = event.clientX;
  handle.setPointerCapture(event.pointerId);
});

handle.addEventListener('pointermove', (event) => {
  if (!handle.hasPointerCapture(event.pointerId)) return;
  const delta = event.clientX - startX;
  if (Math.abs(delta) > 200) {
    // Drag beenden, obwohl die Taste noch gedrückt ist
    handle.releasePointerCapture(event.pointerId);
    console.log('Drag abgebrochen: Grenze erreicht');
  }
});

handle.addEventListener('lostpointercapture', () => {
  console.log('Capture freigegeben');
});

Drag abgebrochen: Grenze erreicht Capture freigegeben

Abbruch per Escape-Taste mit gemerkter pointerId

const canvas = document.querySelector('canvas');
let activePointer = null;

canvas.addEventListener('pointerdown', (event) => {
  activePointer = event.pointerId;
  canvas.setPointerCapture(activePointer);
});

document.addEventListener('keydown', (event) => {
  if (event.key === 'Escape' && activePointer !== null
      && canvas.hasPointerCapture(activePointer)) {
    canvas.releasePointerCapture(activePointer);
    activePointer = null;
    console.log('Zeichnen abgebrochen');
  }
});

Zeichnen abgebrochen

// Wichtig · Fallstricke

Ist pointerId keinem aktiven Zeiger zugeordnet, wirft die Methode eine DOMException vom Typ NotFoundError. Wenn das Element den Zeiger gar nicht erfasst hat, passiert dagegen einfach nichts. Im Zweifel vorher mit hasPointerCapture() prüfen oder den Aufruf in try…catch packen.
Bei pointerup und pointercancel gibt der Browser die Erfassung automatisch frei. Ein zusätzlicher Aufruf ist dann überflüssig.
Das Event lostpointercapture kommt asynchron, also erst vor dem nächsten Pointer-Event, und nicht direkt beim Aufruf.
Bei Touch-Eingaben erfassen manche Browser den Zeiger beim pointerdown implizit. Mit releasePointerCapture() im pointerdown-Handler lässt sich das aufheben, damit pointerover/pointerenter auch auf anderen Elementen feuern.
Wird das Element aus dem DOM entfernt, geht die Erfassung automatisch verloren.
Kompatibilität: Die Methode wird von allen modernen Browsern unterstützt. Der Internet Explorer kannte nur die Vorgängerversion msReleasePointerCapture().

Siehe auch

Element.setPointerCapture() Element.hasPointerCapture() PointerEvent Element.requestPointerLock() Element.setCapture()