CKTIS / JavaScript
MouseEvent: botones del ratón y teclas modificadoras
Identifica el botón del ratón asociado al evento y el estado de Ctrl, Meta, Mayús y Alt. Distingue el código `button` de la máscara de bits `buttons`.
Versión: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxis
event.button
event.ctrlKey
event.metaKey
event.shiftKey
event.altKeybutton, ctrlKey, metaKey, shiftKey y altKey son propiedades de instancia de solo lectura de MouseEvent. Léelas en el objeto del evento, por ejemplo con event.button. Forman parte de la API web, no de ECMAScript 2024, por lo que su disponibilidad depende del entorno de ejecución.
En eventos de pulsación o liberación, como mousedown y mouseup, button contiene el código de un solo botón: 0 principal (normalmente izquierdo), 1 auxiliar (normalmente central), 2 secundario (normalmente derecho), 3 cuarto (habitualmente Atrás), 4 quinto (habitualmente Adelante). Son funciones, no posiciones físicas. En mousemove, button no indica de forma fiable si se mantiene pulsado un botón. buttons es una máscara de los botones pulsados: 0 significa ninguno, y 1, 2, 4, 8, 16 representan, respectivamente, el principal, secundario, auxiliar, cuarto y quinto. (event.buttons & 1) !== 0 comprueba el bit del botón principal.
ctrlKey corresponde a Ctrl, metaKey a Meta (Comando en macOS, tecla Windows en Windows), shiftKey a Mayús y altKey a Alt (Opción en macOS). Cada valor es true si el evento indica que la tecla está pulsada y false en caso contrario. Es el estado registrado en el evento, no una consulta del teclado en tiempo real. El sistema operativo puede interceptar un gesto: en macOS, Ctrl+clic puede abrir un menú contextual en lugar de generar un click normal. Un click no demuestra por sí solo que se haya usado el ratón: también puede proceder del teclado o de una interacción táctil.
En new MouseEvent(type, options), las opciones omitidas button y buttons toman el valor 0, y las opciones de modificadores omitidas toman false. Un evento sintético tiene isTrusted === false y no proporciona la activación del usuario que exigen algunas API.
Ejemplos
// 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}Ejecuta el código en la consola del navegador. En la primera línea, `button: 1` identifica el botón auxiliar y `buttons: 6` combina los bits del secundario (`2`) y del auxiliar (`4`). En la segunda, `button: 0` es el valor predeterminado, mientras que la máscara solo indica el botón secundario. No se despacha ninguno de los dos eventos.
Lecciones relacionadas
- JavaScript · Lección 37 · Avanzado · Versión: 4
- JavaScript · Lección 38 · Avanzado · Versión: 4
- JavaScript · Lección 36 · Intermedio · Versión: 3
- JavaScript · Lección 37 · Intermedio · Versión: 3
Fuentes
- MouseEvent: button property
- MouseEvent: ctrlKey property
- MouseEvent: metaKey property
- MouseEvent: shiftKey property
- MouseEvent: altKey property
- MouseEvent: buttons property
- MouseEvent: MouseEvent() constructor
- Element: click event
- Event: isTrusted property
- HTML Standard: Tracking user activation
- ECMAScript 2024 Language Specification: Hosts and Implementations