Element.hasPointerCapture() — Methode · JavaScript-Referenz

Signatur

Element.prototype.hasPointerCapture(pointerId)

Beschreibung

hasPointerCapture() gibt true zurück, wenn das Element, auf dem die Methode aufgerufen wird, die Zeigererfassung (englisch pointer capture) für den Zeiger mit der angegebenen ID hat. Das ist z. B. nach einem Aufruf von setPointerCapture() der Fall. Solange die Erfassung besteht, gehen alle Zeiger-Ereignisse dieses Zeigers (pointermove, pointerup usw.) an dieses Element, auch wenn sich Maus, Stift oder Finger längst außerhalb des Elements befinden. (Die MDN-Übersetzung „Zeigerdämpfung“ ist irreführend. Gemeint ist die Erfassung.)

Gebraucht wird die Methode vor allem bei eigenen Drag-Interaktionen wie Schiebereglern, Zeichenflächen, verschiebbaren Fenstern oder Größenanfassern. Damit lässt sich prüfen, ob gerade ein Ziehvorgang läuft, ob man die Erfassung vor dem Freigeben noch hat oder ob der Browser sie schon selbst beendet hat.

Die pointerId kommt aus der Eigenschaft PointerEvent.pointerId des jeweiligen Ereignisses. Jeder aktive Zeiger (jeder Finger bei Multitouch, jeder Stift, die Maus) hat eine eigene ID. Deshalb wird die Erfassung auch für jeden Zeiger getrennt verwaltet.

Parameter

Name	Typ	Default	Beschreibung
$pointerId Pflicht	number		Die ID des Zeigers, meist aus `event.pointerId` eines `PointerEvent`.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Element die Erfassung für diesen Zeiger hat, sonst false. Bei einer unbekannten oder ungültigen ID wird false zurückgegeben und kein Fehler geworfen.

Beispiele

Erfassung setzen und prüfen

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

box.addEventListener('pointerdown', (event) => {
  console.log('vorher:', box.hasPointerCapture(event.pointerId));
  box.setPointerCapture(event.pointerId);
  console.log('nachher:', box.hasPointerCapture(event.pointerId));
});

vorher: false (bei Touch oft schon true, siehe Hinweise) nachher: true

Schieberegler: nur ziehen, solange die Erfassung besteht

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

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

thumb.addEventListener('pointermove', (e) => {
  // Nur reagieren, wenn gerade gezogen wird
  if (!thumb.hasPointerCapture(e.pointerId)) return;
  const rect = track.getBoundingClientRect();
  const ratio = Math.min(Math.max((e.clientX - rect.left) / rect.width, 0), 1);
  thumb.style.left = `${ratio * 100}%`;
});

thumb.addEventListener('pointerup', (e) => {
  if (thumb.hasPointerCapture(e.pointerId)) {
    thumb.releasePointerCapture(e.pointerId);
  }
});

Erfassung mit der Escape-Taste sicher abbrechen

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

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

canvas.addEventListener('lostpointercapture', () => {
  activePointer = null;
  console.log('Erfassung beendet');
});

document.addEventListener('keydown', (e) => {
  if (e.key === 'Escape' && activePointer !== null &&
      canvas.hasPointerCapture(activePointer)) {
    canvas.releasePointerCapture(activePointer);
  }
});

Erfassung beendet

// Wichtig · Fallstricke

Implizite Erfassung bei Touch: Viele Browser erfassen Touch-Zeiger bei pointerdown automatisch für das Ziel-Element. Dann liefert hasPointerCapture() dort schon true, ohne dass setPointerCapture() aufgerufen wurde. Bei der Maus ist das nicht so.
Automatisches Freigeben: Nach pointerup oder pointercancel gibt der Browser die Erfassung selbst frei und löst lostpointercapture aus. Das passiert auch, wenn das Element aus dem DOM entfernt wird. Danach liefert die Methode false. Aufräumarbeiten gehören deshalb besser in lostpointercapture als in pointerup.
Sofortiger Status: Direkt nach setPointerCapture() gibt die Methode schon true zurück. Das Ereignis gotpointercapture kommt aber erst vor dem nächsten Zeiger-Ereignis.
Anders als setPointerCapture() und releasePointerCapture() wirft die Methode bei einer ungültigen pointerId keinen NotFoundError.
Funktioniert nur mit Pointer Events, nicht mit den alten mouse- oder touch-Ereignissen. In allen aktuellen Browsern verfügbar, im Internet Explorer nicht (dort gab es nur msSetPointerCapture mit Präfix).

Siehe auch

Element.setPointerCapture() Element.releasePointerCapture() PointerEvent PointerEvent.pointerId new VideoTrackGenerator()