Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

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.

Fonti