Element.setPointerCapture() — Methode · JavaScript-Referenz

Signatur

Element.prototype.setPointerCapture(pointerId)

Beschreibung

setPointerCapture() legt das Element als Capture-Ziel für einen bestimmten Zeiger fest, also für eine Maus, einen Finger oder einen Stift. Danach gehen alle folgenden Pointer-Ereignisse dieses Zeigers (pointermove, pointerup, pointercancel usw.) an dieses Element. Das gilt auch dann, wenn sich der Zeiger außerhalb des Elements oder sogar außerhalb des Browserfensters befindet. Das Ereignis gotpointercapture wird ausgelöst, sobald die Umleitung aktiv ist.

Typische Einsatzfälle sind Drag-and-Drop-Interaktionen, Schieberegler, Zeichenflächen oder Größenänderungs-Griffe. Ohne Pointer-Capture würde die Interaktion abbrechen, sobald der Nutzer den Zeiger zu schnell über den Rand des Elements hinausbewegt. Mit Pointer-Capture kann man sich außerdem den Workaround sparen, pointermove-Listener an document anzuhängen.

Die Umleitung endet automatisch nach pointerup oder pointercancel. Man kann sie auch vorher mit releasePointerCapture() beenden. In beiden Fällen wird lostpointercapture ausgelöst. Ob ein Element den Zeiger gerade hält, prüft man mit hasPointerCapture().

Parameter

Name	Typ	Default	Beschreibung
$pointerId Pflicht	number		Die Kennung des Zeigers, meist aus `event.pointerId` eines `pointerdown`-Ereignisses.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Ziehbares Element mit Pointer-Capture

const box = document.querySelector('#box');
let startX = 0, startY = 0, originX = 0, originY = 0;

box.addEventListener('pointerdown', (e) => {
  box.setPointerCapture(e.pointerId);
  startX = e.clientX;
  startY = e.clientY;
  const rect = box.getBoundingClientRect();
  originX = rect.left;
  originY = rect.top;
});

box.addEventListener('pointermove', (e) => {
  // Nur reagieren, solange dieser Zeiger gefangen ist
  if (!box.hasPointerCapture(e.pointerId)) return;
  box.style.transform = `translate(${originX + e.clientX - startX}px, ${originY + e.clientY - startY}px)`;
});

box.addEventListener('pointerup', (e) => {
  box.releasePointerCapture(e.pointerId);
});

Schieberegler, der auch außerhalb der Leiste weiterfolgt

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

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

track.addEventListener('pointerdown', (e) => {
  track.setPointerCapture(e.pointerId);
  update(e.clientX);
});

track.addEventListener('pointermove', (e) => {
  if (track.hasPointerCapture(e.pointerId)) update(e.clientX);
});

track.addEventListener('lostpointercapture', () => {
  console.log('Endwert:', track.dataset.value);
});

Endwert: 73

Capture-Ereignisse beobachten

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

canvas.addEventListener('pointerdown', (e) => canvas.setPointerCapture(e.pointerId));
canvas.addEventListener('gotpointercapture', (e) => console.log('Capture aktiv für', e.pointerId));
canvas.addEventListener('lostpointercapture', (e) => console.log('Capture beendet für', e.pointerId));

Capture aktiv für 1 Capture beendet für 1

// Wichtig · Fallstricke

Existiert keine aktive Zeigerkennung mit dieser pointerId, wird eine DOMException vom Typ NotFoundError geworfen. Rufen Sie die Methode deshalb am besten direkt in pointerdown auf.
Ist das Element nicht mit dem Dokument verbunden, wird InvalidStateError geworfen. Dasselbe gilt, wenn gleichzeitig ein Pointer-Lock (requestPointerLock()) aktiv ist.
Während Capture aktiv ist, zeigt event.target immer auf das Capture-Element. Hover-Zustände (:hover) und pointerover/pointerenter anderer Elemente werden nicht ausgelöst.
Auf Touch-Geräten brechen Browser-Gesten wie Scrollen oder Zoomen die Interaktion mit pointercancel ab. Mit CSS touch-action: none auf dem Element verhindern Sie das.
Bei Touch-Eingaben setzen Browser meist automatisch ein implizites Capture auf das Element, das pointerdown empfangen hat.
Die Methode wird in allen aktuellen Browsern unterstützt, Safari erst ab Version 13. Die älteren Maus-Ereignisse wie mousemove erfassen Sie damit nicht zuverlässig. Verwenden Sie deshalb konsequent Pointer Events.

Siehe auch

Element.releasePointerCapture() Element.hasPointerCapture() PointerEvent Element.requestPointerLock() FeaturePolicy.getAllowlistForFeature()