Element: gotpointercapture — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("gotpointercapture", handler)

Beschreibung

Das Ereignis gotpointercapture gehört zur Pointer-Events-API. Es wird an einem Element ausgelöst, sobald dieses durch einen Aufruf von Element.setPointerCapture(pointerId) tatsächlich die Erfassung eines Zeigers erhalten hat. Ab diesem Moment gehen alle weiteren Pointer-Events dieses Zeigers (pointermove, pointerup usw.) an das erfassende Element, auch wenn der Zeiger das Element verlässt.

Wichtig: Die Erfassung greift nicht sofort beim Aufruf von setPointerCapture(), sondern erst beim nächsten Pointer-Event. Das gotpointercapture-Ereignis wird direkt vor diesem nächsten Ereignis verschickt. Es ist damit der zuverlässige Zeitpunkt, um z. B. einen „Ziehen"-Zustand visuell zu markieren oder Ressourcen für eine Drag-Interaktion zu initialisieren.

Der Handler erhält ein PointerEvent. Das Ereignis steigt auf (bubbles), ist aber nicht abbrechbar. Registrieren lässt es sich per addEventListener("gotpointercapture", …) oder über die Eigenschaft ongotpointercapture. Das Gegenstück ist lostpointercapture, das nach dem Freigeben der Erfassung (explizit per releasePointerCapture() oder implizit nach pointerup/pointercancel) ausgelöst wird.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"gotpointercapture"`.
$handler Pflicht	(event: PointerEvent) => void		Callback, der ein `PointerEvent` erhält. Wichtige Eigenschaften: `pointerId`, `pointerType` (`"mouse"`, `"pen"`, `"touch"`), `target`.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once`, `capture`, `signal`.

Beispiele

Drag-Zustand markieren mit addEventListener

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

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

handle.addEventListener('gotpointercapture', (e) => {
  handle.classList.add('dragging');
  console.log(`Erfassung erhalten: Zeiger ${e.pointerId} (${e.pointerType})`);
});

handle.addEventListener('lostpointercapture', () => {
  handle.classList.remove('dragging');
  console.log('Erfassung verloren');
});

Erfassung erhalten: Zeiger 1 (mouse) Erfassung verloren

Über die on-Property ongotpointercapture

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

canvas.onpointerdown = (e) => canvas.setPointerCapture(e.pointerId);
canvas.ongotpointercapture = (e) => {
  console.log('Canvas zeichnet jetzt mit Zeiger', e.pointerId);
};

// Handler später wieder entfernen
const stopTracking = () => {
  canvas.ongotpointercapture = null;
};

Canvas zeichnet jetzt mit Zeiger 1

Listener mit removeEventListener entfernen

const box = document.querySelector('.draggable');

const onGotCapture = (e) => {
  console.log('Capture aktiv:', box.hasPointerCapture(e.pointerId));
};

box.addEventListener('pointerdown', (e) => box.setPointerCapture(e.pointerId));
box.addEventListener('gotpointercapture', onGotCapture);

// Nach einer Sekunde nicht mehr reagieren
setTimeout(() => {
  box.removeEventListener('gotpointercapture', onGotCapture);
}, 1000);

Capture aktiv: true

// Wichtig · Fallstricke

Zeitpunkt: setPointerCapture() wirkt verzögert – gotpointercapture wird erst vor dem nächsten Pointer-Event ausgelöst, nicht synchron im Aufruf.
Nur aktive Zeiger: setPointerCapture() mit einer ungültigen oder inaktiven pointerId wirft eine NotFoundError-DOMException, und das Ereignis wird nicht ausgelöst.
Touch: Bei Touch-Eingaben erfassen viele Browser den Zeiger implizit beim pointerdown auf dem Ziel-Element. Dann kann gotpointercapture auch ohne expliziten Aufruf auftreten.
Abgelöste Elemente: Wird das Element während der Erfassung aus dem DOM entfernt, wird am Dokument lostpointercapture ausgelöst.
Kompatibilität: In allen aktuellen Browsern unterstützt (Chrome, Edge, Firefox, Safari ab 13). Sehr alte Safari-Versionen kennen keine Pointer Events.

Siehe auch

Element: lostpointercapture Element.setPointerCapture() Element.releasePointerCapture() Element.hasPointerCapture() PointerEvent Element: pointerdown Element: contextmenu