CKTIS / JavaScript
Captura del puntero: confirmar o abortar un arrastre
Sigue un arrastre mediante `pointerId` y termínalo una sola vez: confirma el resultado al soltar o descártalo si se cancela la interacción o se pierde la captura antes de tiempo.
Versión: Current web platform; runtime support varies
Sintaxis
// 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);Al iniciar el arrastre, guarda el pointerId del puntero que aceptas en pointerdown. Este evento se produce cuando se pulsa el primer botón del ratón o cuando un dedo o la punta del lápiz entra en contacto con la superficie. Actualiza el estado del arrastre solo con eventos pointermove que tengan ese identificador. pointermove puede indicar un cambio de posición o de otra propiedad, como la presión, y puede ocurrir sin contacto ni botones pulsados.
Llama a element.setPointerCapture(pointerId) para seguir el arrastre fuera del elemento. El contacto táctil directo puede activar la captura implícitamente. Si necesitas liberarla antes, usa releasePointerCapture(). Ambos métodos pueden lanzar NotFoundError si el identificador no corresponde a un puntero activo.
Confirma el resultado con pointerup: se levanta el dedo o el lápiz, o se suelta el último botón del ratón que seguía pulsado. A diferencia de mousedown y mouseup, pointerdown y pointerup no se disparan con cada cambio de botón. Descarta el estado provisional con pointercancel: el navegador ha interrumpido la interacción, por ejemplo, para tomar el control de un gesto de desplazamiento o zoom.
Borra el identificador guardado en ambos casos para que la liberación automática de la captura después de pointerup o pointercancel no termine el arrastre por segunda vez. lostpointercapture indica que se ha perdido la captura, no necesariamente que haya terminado el contacto. Aborta el arrastre solo si sigue activo y el evento tiene el mismo identificador.
La captura no bloquea los gestos del navegador: configura su manejo de antemano con la propiedad CSS touch-action y limita none a la zona que lo necesite. Estas API pertenecen a la plataforma web, no a ECMAScript 2024; su disponibilidad depende del entorno de ejecución.
Ejemplos
<!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>Resultado
pointerdown pointermove pointerup: commit
Guarda el ejemplo en un archivo HTML, ábrelo en un navegador y observa la consola de desarrollo. Inicia el arrastre dentro del recuadro con el botón principal del ratón y suéltalo fuera sin mantener pulsada Mayús. En otro arrastre, empieza a mover el ratón, luego mantén pulsada Mayús y sigue moviéndolo sin soltar el botón para probar la pérdida anticipada de captura. La línea `pointermove` aparece como máximo una vez por arrastre.
Lecciones relacionadas
- JavaScript · Lección 35 · Intermedio · Versión: 3