CKTIS / JavaScript
Element.setPointerCapture – einen Zeiger erfassen
Die Methode setPointerCapture(pointerId) leitet nachfolgende Ereignisse eines bestimmten Zeigers an ein ausgewähltes Element weiter, auch wenn der Zeiger dessen Grenzen verlässt. Das erleichtert Ziehbewegungen mit Maus, Touch oder Stift.
Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntax
element.setPointerCapture(pointerId)Rufe Element.setPointerCapture auf einem Element auf, üblicherweise in einem pointerdown-Handler, und übergib event.pointerId. Die Erfassung ersetzt die normale zielbasierte Auswahl anhand der Position. So empfängt das Element weiterhin etwa pointermove-Ereignisse, auch außerhalb seiner Grenzen. Die Methode gibt undefined zurück; sie bewegt oder sperrt den Cursor nicht.
Der Aufruf setzt eine ausstehende Erfassung: hasPointerCapture(pointerId) kann sofort true zurückgeben, noch bevor gotpointercapture ausgelöst wird. releasePointerCapture(pointerId) gibt die Erfassung explizit frei; nach pointerup oder pointercancel gibt der Browser sie automatisch frei. Verwende lostpointercapture, um den Interaktionsstatus aufzuräumen. Bei Touch-Eingaben kann bereits eine implizite Erfassung bestehen.
Eine Kennung, die zu keinem aktiven Zeiger gehört, führt zu NotFoundError. Ist das Element nicht verbunden oder ist Pointer Lock in seinem Dokument aktiv, wird InvalidStateError ausgelöst. Erst wenn die Prüfungen der Zeigerkennung, der Verbindung des Elements und des Pointer-Lock-Status erfolgreich waren, prüft die Methode die übrigen Bedingungen: Ist keine Taste gedrückt und besteht kein Kontakt oder ist das Dokument des Elements nicht das aktive Dokument des Zeigers, setzt die Methode keine Erfassung und löst keinen Fehler aus.
Die Erfassung deaktiviert weder Scrollen noch Zoomen per Touch; das Beispiel verwendet touch-action: none nur für den Demonstrationsbereich. Dies ist eine Browser-API aus der Pointer-Events-Spezifikation und keine Funktion einer bestimmten ECMAScript-Version. Node 24 allein belegt nicht, dass sie verfügbar ist: Prüfe die Methode und teste die Zielbrowser.
Beispiele
const pad = document.createElement('div');
pad.textContent = 'Press, move outside, release';
pad.style.cssText = 'width:220px;height:100px;background:lightblue;touch-action:none;user-select:none';
const log = document.createElement('pre');
document.body.append(pad, log);
if (typeof pad.setPointerCapture !== 'function') {
log.textContent = 'unsupported';
} else {
let activeId = null;
pad.addEventListener('pointerdown', (event) => {
if (activeId !== null) return;
pad.setPointerCapture(event.pointerId);
activeId = event.pointerId;
log.textContent = `pending: ${pad.hasPointerCapture(activeId)}`;
});
pad.addEventListener('pointermove', (event) => {
if (event.pointerId === activeId) {
log.textContent = 'moving';
}
});
pad.addEventListener('lostpointercapture', (event) => {
if (event.pointerId === activeId) {
activeId = null;
log.textContent = 'released';
}
});
}Ergebnis
released
Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.