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

CKTIS / JavaScript

MouseEvent: botão, coordenadas e teclas modificadoras

Os campos de MouseEvent permitem consultar o botão associado a um evento, as coordenadas do ponteiro relativas à área de visualização e o estado de Ctrl, Meta, Shift e Alt. Distingue button de buttons e as coordenadas da área de visualização das coordenadas do documento.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

event.button; event.clientX; event.clientY; event.ctrlKey; event.metaKey; event.shiftKey; event.altKey

MouseEvent é uma interface da API Web do navegador, não faz parte do próprio ECMAScript. As propriedades da instância são só de leitura. Num processador de eventos, lê-as a partir do objeto recebido, por exemplo, event.clientX; MouseEvent.clientX é uma notação da documentação, não o acesso a uma propriedade estática.

MouseEvent.button identifica o botão premido ou libertado: 0 — principal, 1 — auxiliar, 2 — secundário, 3 — normalmente Anterior, 4 — normalmente Seguinte. O botão principal não tem necessariamente de ser o que está fisicamente à esquerda, pois o utilizador pode alterar a configuração. 0 também pode significar um estado não inicializado. Não uses button para determinar que botões estão premidos durante mousemove; para isso, usa a máscara de bits buttons.

MouseEvent.clientX e MouseEvent.clientY fornecem as coordenadas horizontal e vertical em píxeis relativamente à área de visualização (viewport), não ao elemento nem ao documento inteiro. Os limites esquerdo e superior da área de visualização correspondem ao valor 0, mesmo depois de deslocar o documento. Não pressuponhas que as coordenadas têm de ser números inteiros.

MouseEvent.ctrlKey, MouseEvent.metaKey, MouseEvent.shiftKey e MouseEvent.altKey são valores booleanos que descrevem, respetivamente, o estado de Ctrl, Meta, Shift e Alt no momento do evento. Meta corresponde a Command no macOS e à tecla Windows nos teclados Windows. O sistema operativo pode intercetar Meta. No macOS, Ctrl-clique abre um menu de contexto, pelo que ctrlKey não é detetável nesse evento click.

Estes campos e o construtor são amplamente suportados pelos navegadores; a presença de Node 24 num repositório não demonstra o suporte da API do navegador. O exemplo cria um mousedown sintético com dados fixos: não move o ponteiro nem envia o evento para um elemento.

Exemplos

const event = new MouseEvent("mousedown", {
  button: 0,
  clientX: 120,
  clientY: 80,
  ctrlKey: true,
  metaKey: false,
  shiftKey: true,
  altKey: false
});

console.log(JSON.stringify({
  button: event.button,
  x: event.clientX,
  y: event.clientY,
  ctrl: event.ctrlKey,
  meta: event.metaKey,
  shift: event.shiftKey,
  alt: event.altKey
}));

Resultado

{"button":0,"x":120,"y":80,"ctrl":true,"meta":false,"shift":true,"alt":false}

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes