CKTIS / JavaScript
PointerEvent — eventos de puntero y captura
PointerEvent unifica la entrada de ratón, táctil y lápiz. Aprende cómo se combinan los identificadores de puntero, las coordenadas de la ventana gráfica, el ciclo de interacción y la captura al implementar arrastres.
Versión: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxis
new PointerEvent(type, options)
element.addEventListener('pointerdown', handler)
element.setPointerCapture(event.pointerId)
element.releasePointerCapture(event.pointerId)PointerEvent es una interfaz de la Web API del navegador que hereda de MouseEvent y unifica la entrada de ratón, táctil y lápiz. No es una característica de una edición concreta de ECMAScript. Comprueba si está disponible con 'PointerEvent' in window; que Node 24 esté presente en un repositorio no demuestra que el navegador lo admita.
PointerEvent.pointerId identifica un puntero activo; los identificadores pueden reutilizarse más adelante y no son identificadores permanentes de dispositivos. PointerEvent.isPrimary señala el puntero principal de su tipo, no un único puntero global. Por tanto, el ratón y la entrada táctil pueden tener cada uno un puntero principal al mismo tiempo. PointerEvent.clientX y PointerEvent.clientY, heredados de MouseEvent, proporcionan coordenadas relativas a la ventana gráfica en píxeles CSS, no coordenadas relativas al elemento ni al origen del documento.
El ciclo de interacción incluye pointerdown, pointermove y la finalización mediante pointerup o pointercancel. Borra también el estado de interacción cuando se cancela, por ejemplo, si el navegador se hace cargo de un gesto. pointerover/pointerout y pointerenter/pointerleave describen los límites de los elementos; no sustituyen la finalización de la interacción.
Si se llama a element.setPointerCapture(event.pointerId) durante un pointerdown real, los eventos posteriores de ese puntero se dirigen al elemento incluso fuera de sus límites. gotpointercapture y lostpointercapture indican la obtención y la pérdida de la captura; element.releasePointerCapture(event.pointerId) la libera explícitamente. También se libera después de pointerup o pointercancel. La entrada táctil puede obtener la captura de forma implícita. Gestiona la pérdida de captura para evitar que un arrastre quede activo.
Para los gestos personalizados, declara el CSS touch-action apropiado antes de iniciar la interacción; preventDefault() por sí solo no bloquea el desplazamiento ni el zoom de la ventana gráfica. El ejemplo envía deliberadamente eventos sintéticos: comprueba las propiedades y la limpieza del estado, pero no activa entrada de hardware real ni captura del puntero.
Ejemplos
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}`);Resultado
pointerdown 7 true 10,20 pointermove 7 true 15,25 pointerup 7 true 15,25 active=0
El código mostrado y el resultado declarado se verificaron en un entorno aislado mediante el método registrado en la evidencia de verificación de esta versión exacta.