HOWTO · JavaScript

Seguimiento de la posición del mouse en JavaScript

En este tutorial, entenderemos cómo rastrear la posición del mouse en JavaScript usando eventos de mouse.

En esta página

Para seguir el movimiento del puntero, registra una función de retorno para el evento mousemove del navegador. La función recibe un MouseEvent; consulta en ese evento las propiedades de coordenadas en lugar de mantener un estado independiente del puntero. El evento se activa cuando el puntero se mueve por la ventana, así que el controlador puede consultar su posición actualizada en cada movimiento.

Escucha el movimiento del mouse con el evento mousemove

Un detector de eventos tiene un tipo de evento y una función de retorno. En el ejemplo para el navegador, window.addEventListener registra handleMouseMove para mousemove, y la función consulta pageX, pageY, clientX y clientY. Los nombres de las propiedades distinguen entre mayúsculas y minúsculas. El evento mousemove informa del movimiento; no se activa solo porque se haya cargado la página o porque el puntero esté quieto.

El pequeño ejemplo ejecutable muestra cómo la función da formato a los valores del evento. El objeto sencillo es una entrada de muestra para ilustrar los nombres de las propiedades; en una página interactiva, usa un MouseEvent real del navegador.

Ejecuta este ejemplo:

El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.

function handleMouseMove(event) {
  console.log(
    `page: (${event.pageX}, ${event.pageY}); client: (${event.clientX}, ${event.clientY})`
  );
}

handleMouseMove({ pageX: 120, pageY: 240, clientX: 120, clientY: 240 });

Para interactuar con el navegador, usa esta página autónoma. Su contenido alto permite desplazarse por el documento, y el controlador registra ambos pares de coordenadas cada vez que el puntero se mueve sobre la página.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Mouse coordinates</title>
  <style>
    body { min-height: 1600px; font: 16px sans-serif; }
    main { padding: 2rem; }
  </style>
</head>
<body>
  <main>
    <h1>Move the pointer, then scroll</h1>
    <p>Open the browser developer console to compare the coordinate pairs.</p>
  </main>
  <script>
    window.addEventListener('mousemove', (event) => {
      console.log(
        `page: (${event.pageX}, ${event.pageY}); client: (${event.clientX}, ${event.clientY})`
      );
    });
  </script>
</body>
</html>

Elige entre las coordenadas de página y las de la ventana gráfica

pageX y pageY miden la posición del puntero desde la esquina superior izquierda del documento. Incluyen el desplazamiento del documento, por lo que son útiles cuando la posición debe permanecer vinculada al contenido mientras el lector se desplaza. Por ejemplo, usa las coordenadas de página para registrar dónde se encuentra un punto en un documento largo.

clientX y clientY miden la posición desde la esquina superior izquierda de la ventana gráfica visible. El desplazamiento no cambia ese origen. Usa estos valores para posicionar o comparar algo dentro del área del navegador que está visible en ese momento, como un indicador de cursor personalizado o una superposición en la ventana gráfica.

Estos pares describen espacios de coordenadas distintos, así que usa un solo par de forma coherente en cada cálculo. Mezclar una coordenada de página con una de la ventana gráfica puede desplazar el resultado según la distancia de desplazamiento. Para hacer que un elemento siga al puntero también se necesitan eventos del mouse adicionales y lógica para posicionar el elemento; consultar las coordenadas por sí solo no lo mueve.

Compara pageX y clientX al desplazarte

Antes de desplazarse, el origen del documento coincide con el de la ventana gráfica, por lo que los valores horizontales pageX y clientX coinciden, al igual que pageY y clientY. Mueve el puntero y consulta ambos pares en la consola. La primera imagen proporcionada corresponde a la vista prevista de la consola antes del desplazamiento.

Consola de las herramientas de desarrollo del navegador con los pares de coordenadas de página y de la ventana gráfica antes de desplazarse

Después de desplazarse hacia abajo, los valores horizontales suelen seguir coincidiendo, mientras que el valor vertical pageY incluye la distancia recorrida y clientY se sigue midiendo desde el borde superior de la ventana gráfica. La diferencia entre los valores verticales corresponde al desplazamiento actual. La segunda imagen proporcionada corresponde a la vista prevista de la consola después del desplazamiento.

Consola de las herramientas de desarrollo del navegador con valores distintos de pageY y clientY después de desplazarse

Elige clientX y clientY para posiciones relativas a lo que está visible en ese momento. Elige pageX y pageY para posiciones relativas al documento, incluido su contenido desplazado. Para consultar más eventos del mouse del navegador, visita la referencia de eventos del mouse de MDN.