CKTIS / JavaScript
PointerEvent — eventi del puntatore e cattura
PointerEvent unifica gli input di mouse, touch e penna. Scopri come identificatori del puntatore, coordinate della viewport, ciclo di vita dell’interazione e cattura si combinano per implementare il trascinamento.
Versione: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintassi
new PointerEvent(type, options)
element.addEventListener('pointerdown', handler)
element.setPointerCapture(event.pointerId)
element.releasePointerCapture(event.pointerId)PointerEvent è un’interfaccia della Web API del browser che estende MouseEvent e riunisce gli input di mouse, touch e penna. Non è una funzionalità di una specifica edizione di ECMAScript. Verifica la disponibilità con 'PointerEvent' in window; la presenza di Node 24 in un repository non dimostra il supporto del browser.
PointerEvent.pointerId identifica un puntatore attivo; gli identificatori possono essere riutilizzati in seguito e non sono identificatori permanenti dei dispositivi. PointerEvent.isPrimary indica il puntatore principale del suo tipo, non un unico puntatore globale. Mouse e touch possono quindi avere ciascuno un puntatore principale contemporaneamente. PointerEvent.clientX e PointerEvent.clientY, ereditati da MouseEvent, forniscono coordinate relative alla viewport in pixel CSS, non coordinate relative all’elemento o all’origine del documento.
Il ciclo dell’interazione comprende pointerdown, pointermove e la conclusione tramite pointerup o pointercancel. Azzera lo stato dell’interazione anche in caso di annullamento, per esempio quando il browser prende il controllo di un gesto. pointerover/pointerout e pointerenter/pointerleave descrivono i confini degli elementi; non sostituiscono la conclusione dell’interazione.
Chiamando element.setPointerCapture(event.pointerId) durante un vero pointerdown, gli eventi successivi di quel puntatore vengono indirizzati all’elemento anche al di fuori dei suoi confini. gotpointercapture e lostpointercapture segnalano l’acquisizione e la perdita della cattura; element.releasePointerCapture(event.pointerId) la rilascia esplicitamente. Il rilascio avviene anche dopo pointerup o pointercancel. Il touch può ricevere la cattura implicitamente. Gestisci la perdita della cattura per evitare che un trascinamento resti attivo.
Per i gesti personalizzati, dichiara il CSS touch-action appropriato prima che inizi l’interazione; preventDefault() da solo non impedisce lo scorrimento e lo zoom della viewport. L’esempio invia intenzionalmente eventi sintetici: verifica le proprietà e la pulizia dello stato, ma non attiva input hardware reali né la cattura del puntatore.
Esempi
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}`);Risultato
pointerdown 7 true 10,20 pointermove 7 true 15,25 pointerup 7 true 15,25 active=0
Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.