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

CKTIS / JavaScript

MouseEvent: botões do rato e teclas modificadoras

Identifica o botão do rato associado ao evento e o estado de Ctrl, Meta, Shift e Alt. Distingue o código `button` da máscara de bits `buttons`.

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

Sintaxe

event.button
event.ctrlKey
event.metaKey
event.shiftKey
event.altKey

button, ctrlKey, metaKey, shiftKey e altKey são propriedades de instância de MouseEvent acessíveis apenas para leitura. Lê-as no objeto do evento, por exemplo com event.button. Fazem parte da API Web, não de ECMAScript 2024, pelo que a sua disponibilidade depende do ambiente de execução.

Em eventos de pressão ou libertação, como mousedown e mouseup, button contém o código de um único botão: 0 principal (normalmente o esquerdo), 1 auxiliar (normalmente o do meio), 2 secundário (normalmente o direito), 3 quarto (normalmente Retroceder), 4 quinto (normalmente Avançar). São funções, não posições físicas. Em mousemove, button não indica de forma fiável se um botão está premido. buttons é uma máscara de bits dos botões premidos: 0 significa nenhum; 1, 2, 4, 8, 16 representam, pela mesma ordem, o principal, o secundário, o auxiliar, o quarto e o quinto. (event.buttons & 1) !== 0 testa o bit do botão principal.

ctrlKey corresponde a Ctrl, metaKey a Meta (Command no macOS, tecla Windows no Windows), shiftKey a Shift e altKey a Alt (Option no macOS). Cada valor é true se o evento indicar que a tecla estava premida e false caso contrário. É o estado registado no evento, não uma leitura do teclado em tempo real. O sistema operativo pode intercetar um gesto: no macOS, Ctrl+clique pode abrir um menu de contexto em vez de gerar um click normal. Um click não prova por si só que se usou o rato: pode também resultar do teclado ou de um toque no ecrã.

Em new MouseEvent(type, options), as opções button e buttons omitidas assumem o valor 0, e as opções de teclas modificadoras omitidas assumem false. Um evento sintético tem isTrusted === false e não concede a ativação do utilizador exigida por algumas API.

Exemplos

// Use native MouseEvent in browsers. In Node.js, model only the fields read below.
const DemoMouseEvent = globalThis.MouseEvent ?? class extends Event {
  constructor(type, {
    button = 0, buttons = 0,
    ctrlKey = false, metaKey = false, shiftKey = false, altKey = false,
  } = {}) {
    super(type);
    const fields = { button, buttons, ctrlKey, metaKey, shiftKey, altKey };
    for (const [key, value] of Object.entries(fields)) {
      Object.defineProperty(this, key, { value });
    }
  }
};

for (const event of [
  new DemoMouseEvent("mousedown", { button: 1, buttons: 6, ctrlKey: true, shiftKey: true }),
  new DemoMouseEvent("mousemove", { buttons: 2, metaKey: true, altKey: true }),
]) {
  const { type, button, buttons, ctrlKey, metaKey, shiftKey, altKey } = event;
  console.log(JSON.stringify({ type, button, buttons, ctrlKey, metaKey, shiftKey, altKey }));
}

Resultado

{"type":"mousedown","button":1,"buttons":6,"ctrlKey":true,"metaKey":false,"shiftKey":true,"altKey":false}
{"type":"mousemove","button":0,"buttons":2,"ctrlKey":false,"metaKey":true,"shiftKey":false,"altKey":true}

Executa o código na consola do navegador. Na primeira linha, `button: 1` identifica o botão auxiliar, e `buttons: 6` combina os bits do secundário (`2`) e do auxiliar (`4`). Na segunda, `button: 0` é o valor predefinido, e a máscara indica apenas o botão secundário. Nenhum dos eventos é enviado.

Lições relacionadas

  • JavaScript · Lição 37 · Avançado · Versão: 4
  • JavaScript · Lição 38 · Avançado · Versão: 4
  • JavaScript · Lição 36 · Intermédio · Versão: 3
  • JavaScript · Lição 37 · Intermédio · Versão: 3

Fontes