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
- HTML Standard — Event handlers
- MouseEvent: clientX property
- MouseEvent: clientY property
- Coordinate systems
- Element: mousemove event
- Element: mouseleave event
- Element: mouseout event
- Event: currentTarget property
- Element: getBoundingClientRect() method
- MouseEvent: MouseEvent() constructor
- EventTarget: dispatchEvent() method