Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

Cattura del puntatore: confermare o interrompere un trascinamento

Segui un trascinamento tramite `pointerId` e terminalo una sola volta: conferma il risultato al rilascio o scartalo in caso di annullamento o perdita anticipata della cattura.

Versione: Current web platform; runtime support varies

Sintassi

// Handler sketch: supply the element and the five callbacks in your application.
element.addEventListener("pointerdown", onDown);
element.addEventListener("pointermove", onMove);
element.addEventListener("pointerup", onUp);
element.addEventListener("pointercancel", onCancel);
element.addEventListener("lostpointercapture", onLostCapture);

// In onDown, after accepting the pointer for the drag:
// element.setPointerCapture(event.pointerId);
// In onMove, only if the active drag should release capture early:
// element.releasePointerCapture(event.pointerId);

All’inizio del trascinamento, salva il pointerId del puntatore accettato in pointerdown. Questo evento si verifica quando si preme il primo pulsante del mouse oppure quando un dito o la punta della penna tocca la superficie. Aggiorna lo stato del trascinamento solo per gli eventi pointermove con quell’identificatore. pointermove può segnalare un cambio di posizione o di un’altra proprietà, come la pressione, e può verificarsi anche senza contatto o pulsanti premuti.

Chiama element.setPointerCapture(pointerId) per seguire il trascinamento anche fuori dall’elemento. Il contatto tattile diretto può attivare implicitamente la cattura. Se devi rilasciarla prima, usa releasePointerCapture(). Entrambi i metodi possono generare NotFoundError se l’identificatore non corrisponde a un puntatore attivo.

Conferma il risultato su pointerup: il dito o la penna si solleva, oppure si rilascia l’ultimo pulsante del mouse ancora premuto. A differenza di mousedown e mouseup, pointerdown e pointerup non scattano a ogni cambio di stato di un pulsante. Scarta lo stato provvisorio su pointercancel: il browser ha interrotto l’interazione, per esempio per prendere in carico un gesto di scorrimento o zoom.

In entrambi i casi cancella l’identificatore salvato, così il rilascio automatico della cattura dopo pointerup o pointercancel non conclude il trascinamento una seconda volta. lostpointercapture indica che la cattura è stata persa, non necessariamente che il contatto sia terminato. Interrompi il trascinamento solo se è ancora in corso e l’evento ha lo stesso identificatore.

La cattura non blocca i gesti del browser: configurali in anticipo con la proprietà CSS touch-action e limita none alla zona che ne ha bisogno. Queste API fanno parte della piattaforma web, non di ECMAScript 2024; la disponibilità dipende dall’ambiente di esecuzione.

Esempi

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Drag with pointer capture</title>
  <style>
    #pad {
      position: fixed;
      top: 16px;
      left: 16px;
      z-index: 9999;
      width: 220px;
      height: 100px;
      padding: 12px;
      background: #def;
      color: #123;
      border: 2px solid #246;
      touch-action: none;
      user-select: none;
    }
  </style>
</head>
<body>
  <div id="pad">Start dragging here</div>
  <script>
    (() => {
      const pad = document.getElementById('pad');
      let activeId = null;
      let moved = false;

      pad.addEventListener('pointerdown', (event) => {
        if (activeId !== null || event.button !== 0) return;
        pad.setPointerCapture(event.pointerId);
        activeId = event.pointerId;
        moved = false;
        console.log('pointerdown');
      });

      pad.addEventListener('pointermove', (event) => {
        if (event.pointerId !== activeId) return;
        if (!moved) {
          moved = true;
          console.log('pointermove');
        }
        if (event.shiftKey && pad.hasPointerCapture(event.pointerId)) {
          pad.releasePointerCapture(event.pointerId);
        }
      });

      function finish(event, result) {
        if (event.pointerId !== activeId) return;
        activeId = null;
        console.log(`${event.type}: ${result}`);
      }

      pad.addEventListener('pointerup', (event) => finish(event, 'commit'));
      pad.addEventListener('pointercancel', (event) => finish(event, 'abort'));
      pad.addEventListener('lostpointercapture', (event) => finish(event, 'abort'));
    })();
  </script>
</body>
</html>

Risultato

pointerdown
pointermove
pointerup: commit

Salva l’esempio come file HTML, aprilo nel browser e osserva la console per sviluppatori. Inizia a trascinare nel riquadro con il pulsante principale del mouse e rilascialo fuori senza tenere premuto Maiusc. In un altro trascinamento, inizia a muovere il mouse, poi tieni premuto Maiusc e continua a muoverlo senza rilasciare il pulsante per provare la perdita anticipata della cattura. La riga `pointermove` compare al massimo una volta per trascinamento.

Lezioni correlate

  • JavaScript · Lezione 35 · Intermedio · Versione: 3

Fonti