Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

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.

Fuentes