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