MouseEvent.buttons — Eigenschaft · JavaScript-Referenz

Signatur

MouseEvent.buttons

Beschreibung

MouseEvent.buttons liefert eine Bitmaske. Jede gedrückte Taste setzt ein eigenes Bit, darum lassen sich auch mehrere gleichzeitig gedrückte Tasten erkennen. Die Werte:

0 – keine Taste gedrückt
1 – Haupttaste (meist links)
2 – Sekundärtaste (meist rechts)
4 – Hilfstaste (meist Mausrad/Mitte)
8 – 4. Taste (typisch „Zurück“ im Browser)
16 – 5. Taste (typisch „Vorwärts“ im Browser)

Anders als MouseEvent.button, das nur angibt, welche Taste das aktuelle Ereignis ausgelöst hat, zeigt buttons den Gesamtzustand aller Tasten. Darum eignet sich die Eigenschaft besonders für mousemove- und pointermove-Handler. Dort hat button keine sinnvolle Aussage, aber mit buttons lässt sich z. B. prüfen, ob der Nutzer beim Ziehen gerade die linke Taste gedrückt hält (Zeichenprogramme, Drag-Interaktionen, Auswahlrahmen).

Einzelne Tasten prüft man mit dem bitweisen UND-Operator, etwa (event.buttons & 1) !== 0. Ein direkter Vergleich wie event.buttons === 1 ist nur dann richtig, wenn ausschließlich die linke Taste gedrückt sein darf. Da PointerEvent von MouseEvent erbt, gibt es die Eigenschaft auch bei Zeiger-Ereignissen (Stift, Touch).

Rückgabewert

Typ

number

Beschreibung

Ganzzahlige Bitmaske aus den Werten 1, 2, 4, 8 und 16, zusammengesetzt aus allen zum Zeitpunkt des Ereignisses gedrückten Tasten. 0 bedeutet, dass keine Taste gedrückt ist.

Beispiele

Gedrückte Tasten beim Klicken auflisten

const TASTEN = [
  [1, 'links'],
  [2, 'rechts'],
  [4, 'Mitte'],
  [8, 'Zurück'],
  [16, 'Vorwärts']
];

document.addEventListener('mousedown', (event) => {
  const gedrueckt = TASTEN
    .filter(([bit]) => (event.buttons & bit) !== 0)
    .map(([, name]) => name);
  console.log(`buttons=${event.buttons}:`, gedrueckt.join(', '));
});

// Linke Taste gedrückt halten, dann rechte dazu drücken: buttons=1: links buttons=3: links, rechts

Zeichnen nur bei gedrückter linker Taste (mousemove)

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');

canvas.addEventListener('mousemove', (event) => {
  // Bit 1 = Haupttaste; weitere Tasten dürfen zusätzlich gedrückt sein
  if ((event.buttons & 1) === 0) return;

  ctx.fillRect(event.offsetX, event.offsetY, 2, 2);
});

Kontextmenü-Taste beim Ziehen erkennen (Pointer Events)

const box = document.querySelector('#flaeche');

// Standard-Kontextmenü unterdrücken, damit Rechts-Ziehen funktioniert
box.addEventListener('contextmenu', (e) => e.preventDefault());

box.addEventListener('pointermove', (event) => {
  if (event.buttons === 2) {
    box.style.transform = `translate(${event.offsetX}px, ${event.offsetY}px)`;
  }
});

Synthetisches Ereignis mit buttons erzeugen

const ev = new MouseEvent('mousemove', {
  bubbles: true,
  buttons: 1 | 4 // links + Mitte
});

console.log(ev.buttons);
console.log((ev.buttons & 4) !== 0);

5 true

// Wichtig · Fallstricke

Nummerierung beachten: Die Bitwerte von buttons entsprechen nicht den Werten von button. Für die rechte Taste gilt buttons = 2, aber button = 2 heißt ebenfalls „rechts“, während die mittlere Taste bei buttons den Wert 4 hat und bei button den Wert 1. Diese beiden Eigenschaften also nicht verwechseln.
Bitweise prüfen: Ein Vergleich wie event.buttons === 1 schlägt fehl, sobald zusätzlich eine andere Taste gedrückt ist. Besser ist (event.buttons & 1) !== 0.
mouseup / click: Bei mouseup und click ist die gerade losgelassene Taste in buttons schon nicht mehr enthalten, oft ist der Wert deshalb 0. Welche Taste losgelassen wurde, verrät hier nur button.
Linkshänder-Einstellungen: Wurden die Tasten im Betriebssystem vertauscht, steht 1 für die physisch rechte Taste. Gemeint ist also die „Haupttaste“, nicht zwingend die linke.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Safari kennt die Eigenschaft erst ab Version 11.1; ältere Versionen liefern undefined. Die Tasten 4 und 5 meldet nicht jede Hardware bzw. jeder Treiber zuverlässig, und manche Browser lösen darauf direkt eine Navigation (Zurück/Vorwärts) aus.
Touch/Stift: Bei PointerEvent steht Kontakt mit einem Stift oder Finger für 1, die Radiertaste eines Stifts für 32.

Siehe auch

MathMLElement.autofocus MouseEvent.button MouseEvent.altKey MouseEvent.metaKey MouseEvent.screenX