Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

Element.setPointerCapture — catturare un puntatore

Il metodo setPointerCapture(pointerId) indirizza gli eventi successivi di un determinato puntatore a un elemento scelto, anche quando il puntatore esce dai suoi limiti. Semplifica il trascinamento con mouse, tocco o penna.

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

element.setPointerCapture(pointerId)

Chiama Element.setPointerCapture su un elemento, di solito all’interno di un gestore pointerdown, passando event.pointerId. La cattura sostituisce la normale selezione del destinatario basata sulla posizione, così l’elemento continua a ricevere eventi come pointermove anche al di fuori dei suoi limiti. Il metodo restituisce undefined; non sposta né blocca il cursore.

La chiamata imposta una cattura in attesa: hasPointerCapture(pointerId) può restituire subito true, prima ancora di gotpointercapture. releasePointerCapture(pointerId) la rilascia esplicitamente; dopo pointerup o pointercancel, il browser la rilascia automaticamente. Usa lostpointercapture per ripulire lo stato dell’interazione. L’input touch potrebbe avere già una cattura implicita.

Un identificatore che non corrisponde ad alcun puntatore attivo causa NotFoundError. Un elemento scollegato o un Pointer Lock attivo nel suo documento causa InvalidStateError. Solo dopo aver superato i controlli sull’identificatore del puntatore, sulla connessione dell’elemento e sullo stato di Pointer Lock, il metodo verifica le condizioni rimanenti: se non c’è alcun pulsante premuto né alcun contatto, oppure se il documento dell’elemento non è quello attivo del puntatore, il metodo non imposta la cattura e non genera errori.

La cattura non disabilita lo scorrimento o lo zoom touch; l’esempio usa touch-action: none solo nell’area dimostrativa. Questa è un’API del browser definita da Pointer Events, non una funzionalità di una specifica edizione ECMAScript. La presenza di Node 24 non ne dimostra la disponibilità: verifica il metodo e prova i browser di destinazione.

Esempi

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';
    }
  });
}

Risultato

released

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