MouseEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface MouseEvent extends UIEvent

Beschreibung

MouseEvent ist die Grundlage für alle Ereignisse, die ein Zeigegerät auslöst. Dazu gehören click, dblclick, mousedown, mouseup, mousemove, mouseover, mouseout, mouseenter, mouseleave und contextmenu. Die Schnittstelle erbt von UIEvent und damit von Event. Von ihr abgeleitet sind PointerEvent, WheelEvent und DragEvent.

Wichtige Eigenschaften:

Koordinaten: clientX/clientY (relativ zum Viewport), pageX/pageY (relativ zum Dokument, inklusive Scrollposition), screenX/screenY (relativ zum Bildschirm), offsetX/offsetY (relativ zum Padding-Rand des Zielelements) sowie movementX/movementY (Differenz zum letzten mousemove).
Tasten: button ist die Taste, die das Ereignis ausgelöst hat (0 = links, 1 = Mitte, 2 = rechts, 3/4 = Zurück/Vor). buttons ist eine Bitmaske aller gerade gedrückten Tasten (1 = links, 2 = rechts, 4 = Mitte).
Zusatztasten: altKey, ctrlKey, shiftKey und metaKey sowie die Methode getModifierState(key).
Beteiligte Elemente: relatedTarget ist bei mouseover/mouseout bzw. mouseenter/mouseleave das Element, das der Zeiger gerade verlassen bzw. betreten hat.

Mit dem Konstruktor new MouseEvent(type, options) lassen sich eigene Mausereignisse erzeugen und über dispatchEvent() auslösen, zum Beispiel in Tests. Solche synthetischen Ereignisse haben isTrusted === false. Viele Browser-Aktionen (Popups öffnen, Vollbild, Zwischenablage) setzen jedoch eine echte Nutzeraktivierung voraus.

Für neue Projekte sind oft PointerEvents (pointerdown, pointermove …) die bessere Wahl. Sie decken Maus, Stift und Touch mit einer einzigen API ab und haben alle Eigenschaften von MouseEvent.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, z. B. `"click"`, `"mousedown"` oder `"mousemove"`.
$options	MouseEventInit	{}	Optionales Objekt mit Initialwerten. Es akzeptiert alle Felder von `EventInit`/`UIEventInit` (`bubbles`, `cancelable`, `composed`, `view`, `detail`).
$options.screenX / options.screenY	number	0	Koordinaten relativ zum Bildschirm.
$options.clientX / options.clientY	number	0	Koordinaten relativ zum Viewport.
$options.button	number	0	Auslösende Taste: 0 = links, 1 = Mitte, 2 = rechts, 3 = Zurück, 4 = Vor.
$options.buttons	number	0	Bitmaske der gedrückten Tasten: 1 = links, 2 = rechts, 4 = Mitte, 8 = Zurück, 16 = Vor.
$options.ctrlKey / shiftKey / altKey / metaKey	boolean	false	Gibt an, ob die jeweilige Zusatztaste gedrückt ist.
$options.relatedTarget	EventTarget \| null	null	Zweites beteiligtes Element, z. B. bei `mouseover`/`mouseout`.
$options.movementX / options.movementY	number	0	Relative Bewegung seit dem letzten `mousemove`.

Rückgabewert

Typ

MouseEvent

Beschreibung

Beim Aufruf mit new MouseEvent(type, options) ein neues, noch nicht ausgelöstes MouseEvent-Objekt. Zum Auslösen wird es an dispatchEvent() übergeben.

Beispiele

Klickposition und Zusatztasten auswerten

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

box.addEventListener('click', (event) => {
  console.log(`Viewport: ${event.clientX}/${event.clientY}`);
  console.log(`Im Element: ${event.offsetX}/${event.offsetY}`);
  console.log(`Dokument: ${event.pageX}/${event.pageY}`);

  if (event.ctrlKey || event.metaKey) {
    console.log('Mehrfachauswahl aktiv');
  }
});

Viewport: 120/80 Im Element: 20/15 Dokument: 120/680 Mehrfachauswahl aktiv

Maustasten unterscheiden und Kontextmenü ersetzen

const canvas = document.querySelector('canvas');
const tastenNamen = ['links', 'Mitte', 'rechts', 'Zurück', 'Vor'];

canvas.addEventListener('mousedown', (event) => {
  console.log(`Taste: ${tastenNamen[event.button]}`);
  // Bitmaske: Sind links UND rechts gleichzeitig gedrückt?
  if ((event.buttons & 3) === 3) console.log('Beide Tasten gedrückt');
});

// Eigenes Kontextmenü statt Browser-Menü
canvas.addEventListener('contextmenu', (event) => {
  event.preventDefault();
  console.log('Eigenes Menü bei', event.clientX, event.clientY);
});

Taste: rechts Eigenes Menü bei 200 150

Element ziehen (Drag) mit mousemove und removeEventListener

const handle = document.querySelector('.draggable');
let startX = 0;
let startY = 0;

const onMove = (event) => {
  handle.style.transform = `translate(${event.clientX - startX}px, ${event.clientY - startY}px)`;
};

const onUp = () => {
  // Listener wieder entfernen, sobald die Taste losgelassen wird
  document.removeEventListener('mousemove', onMove);
  document.removeEventListener('mouseup', onUp);
};

handle.addEventListener('mousedown', (event) => {
  if (event.button !== 0) return; // nur linke Taste
  startX = event.clientX;
  startY = event.clientY;
  document.addEventListener('mousemove', onMove);
  document.addEventListener('mouseup', onUp);
});

Synthetisches Klick-Ereignis erzeugen (z. B. in Tests)

const button = document.querySelector('#speichern');
button.onclick = (event) => {
  console.log('Geklickt, vertrauenswürdig:', event.isTrusted, 'Shift:', event.shiftKey);
};

const klick = new MouseEvent('click', {
  bubbles: true,
  cancelable: true,
  clientX: 50,
  clientY: 25,
  shiftKey: true,
});

const nichtAbgebrochen = button.dispatchEvent(klick);
console.log('dispatchEvent-Ergebnis:', nichtAbgebrochen);

Geklickt, vertrauenswürdig: false Shift: true dispatchEvent-Ergebnis: true

Siehe auch

CloseEvent FocusEvent PushEvent TouchEvent MessageEvent MouseScrollEvent