CKTIS / JavaScript
PointerEvent — Zeigereingaben und Pointer Capture
PointerEvent vereinheitlicht Eingaben mit Maus, Touch und Stift. Erfahre, wie Zeigerkennungen, Viewport-Koordinaten, Interaktionsabläufe und Pointer Capture beim Implementieren von Ziehbewegungen zusammenspielen.
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
new PointerEvent(type, options)
element.addEventListener('pointerdown', handler)
element.setPointerCapture(event.pointerId)
element.releasePointerCapture(event.pointerId)PointerEvent ist eine Browser-Web-API-Schnittstelle, die von MouseEvent erbt und Maus-, Touch- und Stifteingaben vereinheitlicht. Sie ist kein Merkmal einer bestimmten ECMAScript-Version. Prüfe die Verfügbarkeit mit 'PointerEvent' in window; Node 24 in einem Repository belegt keine Browserunterstützung.
PointerEvent.pointerId identifiziert einen aktiven Zeiger; Kennungen können später wiederverwendet werden und sind keine dauerhaften Gerätekennungen. PointerEvent.isPrimary bezeichnet den primären Zeiger seines Typs, nicht einen einzigen globalen Zeiger. Daher können Maus und Touch gleichzeitig jeweils einen primären Zeiger haben. PointerEvent.clientX und PointerEvent.clientY, von MouseEvent geerbt, liefern Viewport-bezogene Koordinaten in CSS-Pixeln, nicht elementbezogene oder auf den Dokumentursprung bezogene Koordinaten.
Der Interaktionsablauf umfasst pointerdown, pointermove und die Beendigung durch pointerup oder pointercancel. Lösche den Interaktionszustand auch bei einem Abbruch, zum Beispiel wenn der Browser eine Geste übernimmt. pointerover/pointerout und pointerenter/pointerleave beschreiben Elementgrenzen; sie ersetzen nicht das Beenden der Interaktion.
Wird element.setPointerCapture(event.pointerId) während eines echten pointerdown aufgerufen, werden nachfolgende Ereignisse für diesen Zeiger auch außerhalb der Elementgrenzen an das Element geleitet. gotpointercapture und lostpointercapture melden den Beginn und Verlust der Erfassung; element.releasePointerCapture(event.pointerId) gibt sie ausdrücklich frei. Nach pointerup oder pointercancel wird sie ebenfalls freigegeben. Bei Touch kann die Erfassung automatisch erfolgen. Behandle den Verlust der Erfassung, damit ein Ziehvorgang nicht aktiv bleibt.
Lege für eigene Gesten das passende CSS touch-action fest, bevor die Interaktion beginnt; preventDefault() allein verhindert weder das Verschieben noch das Zoomen des Viewports. Das Beispiel löst absichtlich synthetische Ereignisse aus: Es prüft Eigenschaften und das Bereinigen des Zustands, aber keine echte Hardwareeingabe oder Pointer Capture.
Beispiele
const target = document.createElement('div');
const active = new Map();
const lines = [];
for (const type of ['pointerdown', 'pointermove', 'pointerup', 'pointercancel']) {
target.addEventListener(type, (event) => {
const { pointerId, isPrimary, clientX, clientY } = event;
if (type === 'pointerdown') active.set(pointerId, true);
if (!active.has(pointerId)) return;
lines.push(`${type} ${pointerId} ${isPrimary} ${clientX},${clientY}`);
if (type === 'pointerup' || type === 'pointercancel') {
active.delete(pointerId);
}
});
}
for (const [type, clientX, clientY] of [
['pointerdown', 10, 20],
['pointermove', 15, 25],
['pointerup', 15, 25]
]) {
target.dispatchEvent(new PointerEvent(type, {
pointerId: 7, pointerType: 'touch', isPrimary: true,
clientX, clientY
}));
}
console.log(lines.join('\n'));
console.log(`active=${active.size}`);Ergebnis
pointerdown 7 true 10,20 pointermove 7 true 15,25 pointerup 7 true 15,25 active=0
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.