new MouseEvent() — Methode · JavaScript-Referenz

Signatur

new MouseEvent(type, options)

Beschreibung

Mit new MouseEvent() erzeugst du programmgesteuert Mausereignisse wie click, mousedown, mouseup, mousemove, mouseover oder contextmenu. Das erzeugte Objekt wird erst wirksam, wenn es mit EventTarget.dispatchEvent() auf einem Element ausgelöst wird.

Typische Einsatzgebiete sind automatisierte Tests (Unit- und Integrationstests ohne echten Benutzer), das Weiterleiten von Interaktionen an andere Elemente sowie das Simulieren von Mausbewegungen, etwa für Drag-Logik oder Tooltips. Über das Options-Objekt legst du Koordinaten, gedrückte Tasten, Modifikatortasten (Strg, Umschalt, Alt, Meta) und das Bubbling-Verhalten fest.

Wichtig: Synthetische Events haben isTrusted === false. Browser behandeln sie daher nicht wie echte Benutzeraktionen. Aktionen, die eine Benutzeraktivierung erfordern (Pop-ups öffnen, Vollbild, Zwischenablage, Audio-Autoplay), werden dadurch nicht freigeschaltet. Außerdem ist standardmäßig bubbles: false – Event-Delegation greift nur, wenn du bubbles: true explizit setzt.

Der Konstruktor ersetzt die veraltete Kombination aus document.createEvent('MouseEvents') und initMouseEvent().

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, z. B. `"click"`, `"mousedown"`, `"mousemove"`, `"dblclick"`, `"contextmenu"`. Groß-/Kleinschreibung wird beachtet.
$options	MouseEventInit	{}	Optionales Objekt. Erbt von `EventInit`/`UIEventInit`/`EventModifierInit`. Wichtige Felder: `bubbles` (boolean, Standard `false`) – steigt das Event im DOM auf? `cancelable` (boolean, Standard `false`) – kann `preventDefault()` wirken? `composed` (boolean, Standard `false`) – überquert es Shadow-DOM-Grenzen? `view` (Window\|null) – meist `window`. `detail` (number) – z. B. Klickanzahl. `screenX`, `screenY`, `clientX`, `clientY` (number, Standard `0`) – Koordinaten. `movementX`, `movementY` (number) – relative Bewegung. `ctrlKey`, `shiftKey`, `altKey`, `metaKey` (boolean, Standard `false`) – Modifikatortasten. `button` (number, Standard `0`) – auslösende Taste: 0 links, 1 Mitte, 2 rechts, 3 zurück, 4 vorwärts. `buttons` (number, Standard `0`) – Bitmaske gedrückter Tasten: 1 links, 2 rechts, 4 Mitte. `relatedTarget` (EventTarget\|null) – z. B. bei `mouseover`/`mouseout` das verlassene bzw. betretene Element.

Rückgabewert

Typ

MouseEvent

Beschreibung

Ein neues MouseEvent-Objekt mit den übergebenen Eigenschaften und isTrusted === false. Es wird noch nicht ausgelöst – dafür dispatchEvent() verwenden.

Beispiele

Klick auf einen Button simulieren

const button = document.createElement('button');
button.textContent = 'Speichern';
document.body.append(button);

button.addEventListener('click', (event) => {
  console.log('Geklickt!', event.isTrusted, event.clientX, event.clientY);
});

const klick = new MouseEvent('click', {
  bubbles: true,
  cancelable: true,
  view: window,
  clientX: 120,
  clientY: 45
});

const nichtAbgebrochen = button.dispatchEvent(klick);
console.log('Standardaktion ausgeführt:', nichtAbgebrochen);

Geklickt! false 120 45 Standardaktion ausgeführt: true

Rechtsklick mit Strg-Taste für Kontextmenü-Tests

const liste = document.createElement('ul');
liste.innerHTML = '<li>Datei A</li><li>Datei B</li>';
document.body.append(liste);

// Event-Delegation am Elternelement – funktioniert nur mit bubbles: true
liste.addEventListener('contextmenu', (event) => {
  event.preventDefault();
  const taste = event.button === 2 ? 'rechts' : 'andere';
  console.log(`Kontextmenü für "${event.target.textContent}" (Taste: ${taste}, Strg: ${event.ctrlKey})`);
});

const zweitesItem = liste.children[1];
const ereignis = new MouseEvent('contextmenu', {
  bubbles: true,
  cancelable: true,
  button: 2,
  buttons: 2,
  ctrlKey: true
});

const ergebnis = zweitesItem.dispatchEvent(ereignis);
console.log('defaultPrevented:', ereignis.defaultPrevented, '| Rückgabe:', ergebnis);

Kontextmenü für "Datei B" (Taste: rechts, Strg: true) defaultPrevented: true | Rückgabe: false

Drag-Bewegung für einen Test nachstellen

const box = document.createElement('div');
document.body.append(box);

let start = null;
box.addEventListener('mousedown', (e) => { start = { x: e.clientX, y: e.clientY }; });
document.addEventListener('mousemove', (e) => {
  if (start && e.buttons & 1) {
    console.log(`Verschoben um ${e.clientX - start.x}px / ${e.clientY - start.y}px`);
  }
});
document.addEventListener('mouseup', () => { start = null; console.log('Losgelassen'); });

const sende = (ziel, typ, x, y, buttons) =>
  ziel.dispatchEvent(new MouseEvent(typ, { bubbles: true, clientX: x, clientY: y, buttons }));

sende(box, 'mousedown', 10, 10, 1);
sende(box, 'mousemove', 50, 30, 1);
sende(box, 'mouseup', 50, 30, 0);

Verschoben um 40px / 20px Losgelassen

// Wichtig · Fallstricke

Standardwert für bubbles ist false: Ohne bubbles: true erreichen synthetische Events weder Eltern-Listener noch Event-Delegation – der häufigste Fehler.
isTrusted ist immer false: Synthetische Events lösen keine Benutzeraktivierung aus. window.open(), requestFullscreen(), Clipboard-Schreibzugriffe oder das Öffnen eines Datei-Dialogs können blockiert werden. Serverseitig oder in sicherheitsrelevanter Logik niemals darauf vertrauen, dass ein Klick echt ist.
Standardaktionen: Ein synthetisches click auf einem Link oder einer Checkbox löst in modernen Browsern die Aktivierung aus (Navigation bzw. Umschalten). Andere Events wie mousedown setzen dagegen keinen Fokus und starten keine Textauswahl. Für einfache Klicks ist HTMLElement.click() oft die kürzere Alternative.
button und buttons unterscheiden sich: button nennt die auslösende Taste (0 links, 2 rechts), buttons ist eine Bitmaske (1 links, 2 rechts, 4 Mitte). Die Werte für rechts/Mitte sind vertauscht.
pageX/pageY, offsetX/offsetY lassen sich nicht direkt setzen, sie werden aus clientX/clientY abgeleitet.
Für Zeigergeräte allgemein (Stift, Touch) ist PointerEvent vorzuziehen, da moderne Frameworks oft auf pointerdown statt mousedown hören.
Kompatibilität: in allen modernen Browsern verfügbar; der Internet Explorer unterstützt den Konstruktor nicht (dort nur das veraltete initMouseEvent()).

Siehe auch

new CloseEvent() new FocusEvent() new PushEvent() new TouchEvent() new MessageEvent() new BarcodeDetector() new ClipboardEvent()