Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Coordenadas do rato: clientX, clientY, mousemove e mouseleave

Lê a posição do ponteiro na área de visualização, atualiza a interface durante o movimento e repõe o estado quando o ponteiro sai de um elemento e dos seus descendentes.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

element.addEventListener("mousemove", onMove);
element.addEventListener("mouseleave", onLeave);
// Inside a listener receiving a MouseEvent:
const x = event.clientX;
const y = event.clientY;

clientX e clientY são propriedades só de leitura de uma instância de MouseEvent. Indicam a posição horizontal e vertical do ponteiro no momento do evento, em píxeis CSS a partir do canto superior esquerdo da área de visualização (viewport). Não são coordenadas do documento, do ecrã nem do elemento. Estas API pertencem à plataforma Web, não ao ECMAScript 2024; a sua disponibilidade depende do ambiente de execução.

mousemove é disparado quando o ponteiro se move sobre um elemento, mesmo sem nenhum botão premido. Pode ocorrer com muita frequência, por isso evita trabalho pesado no manipulador. O evento propaga-se para cima na árvore DOM: se vier de um descendente, event.target pode identificar esse descendente, enquanto event.currentTarget identifica, durante a execução do manipulador, o elemento onde foi registado o listener.

mouseleave é disparado quando o ponteiro sai do elemento e de todos os seus descendentes. Ao contrário de mouseout, não se propaga para cima. Passar do elemento para um descendente não dispara mouseleave nesse elemento. O que conta é a árvore DOM, não apenas o retângulo visível. Usa este evento para repor o estado de passagem do rato, mas repõe-no explicitamente se o elemento for removido ou substituído.

Para obter uma posição relativa ao canto superior esquerdo do retângulo delimitador do elemento, obtém rect com event.currentTarget.getBoundingClientRect() dentro do manipulador e calcula event.clientX - rect.left e event.clientY - rect.top. Ambos os pares usam o mesmo sistema de coordenadas, por isso não somes o deslocamento da página. A subtração não desfaz as transformações CSS.

Exemplos

<!doctype html>
<meta charset="utf-8">
<title>Mouse event propagation</title>
<pre id="output"></pre>
<script>
(() => {
  const output = document.getElementById("output");
  const lines = [];
  function log(line) {
    lines.push(line);
    console.log(line);
  }

  const area = document.createElement("div");
  const child = document.createElement("span");
  area.append(child);

  area.addEventListener("mousemove", (event) => {
    log(`move: ${event.clientX}, ${event.clientY}`);
  });
  area.addEventListener("mouseleave", () => log("leave"));

  child.dispatchEvent(new MouseEvent("mousemove", {
    bubbles: true, clientX: 24, clientY: 36
  }));
  child.dispatchEvent(new MouseEvent("mouseleave", { bubbles: false }));
  area.dispatchEvent(new MouseEvent("mouseleave", { bubbles: false }));

  output.textContent = lines.join("\n");
})();
</script>

Resultado

move: 24, 36
leave

Guarda o exemplo como ficheiro HTML e abre-o num navegador. Os elementos não estão ligados ao documento e os eventos são sintéticos (`isTrusted` é `false`): não movem o ponteiro nem verificam qual é o elemento que está por baixo. O `mousemove` do filho chega ao elemento pai. Só o `mouseleave` enviado diretamente ao pai escreve `leave`.

Lições relacionadas

  • JavaScript · Lição 12 · Avançado · Versão: 4

Fontes