</> programmierung.net
Start · Sprachen · JavaScript · Referenz · new PointerEvent()

new PointerEvent()

Methode

Erstellt ein neues, synthetisches <code>PointerEvent</code>-Objekt, das sich mit <code>dispatchEvent()</code> an ein Element senden lässt. <code>isTrusted</code> ist dabei <code>false</code>.

seit JavaScript Baseline: alle modernen Browser (seit 2020) Kategorie: webapi

Signatur

new PointerEvent(type, options)

Beschreibung

Der Konstruktor PointerEvent() erzeugt ein Zeigerereignis in Ihrem eigenen Code. Pointer Events fassen Maus, Stift und Touch in einem gemeinsamen Ereignismodell zusammen. Ein selbst erzeugtes Ereignis kann Werte wie pointerId, pointerType, pressure, width/height oder die Neigungswinkel des Stifts enthalten.

Man verwendet den Konstruktor vor allem für automatisierte Tests von Zeichen-, Drag-and-Drop- oder Gestenlogik, für Simulationen (z. B. ein Tutorial, das eine Eingabe vorführt) und um Eingaben einer eigenen Komponente an andere Teile der Anwendung weiterzuleiten.

Das erzeugte Ereignis ist unzuverlässig (event.isTrusted === false). Der Browser führt dafür keine Standardaktionen aus. Es gibt also kein Scrollen, keinen Fokuswechsel, keine Textauswahl, und es wird kein click daraus erzeugt. Auch Funktionen, die eine echte Nutzerinteraktion voraussetzen (Vollbild, Pop-ups, Zwischenablage), werden dadurch nicht freigeschaltet. Das Ereignis wird erst mit element.dispatchEvent(event) ausgelöst, und zwar synchron.

PointerEvent erbt von MouseEvent. Deshalb akzeptiert options auch alle Felder aus MouseEventInit (clientX, clientY, button, buttons, ctrlKey …) und EventInit (bubbles, cancelable, composed).

Parameter

Name Typ Default Beschreibung
$type Pflicht string Name des Ereignisses, z. B. "pointerdown", "pointermove", "pointerup", "pointercancel", "pointerover", "pointerenter", "pointerleave", "gotpointercapture".
$options PointerEventInit {} Optionales Objekt mit Startwerten. Zusätzlich zu den Feldern von MouseEventInit/EventInit möglich:
  • pointerId (number, Standard 0)
  • pointerType ("mouse" | "pen" | "touch" | "", Standard "")
  • isPrimary (boolean, Standard false)
  • width, height (number, Standard 1)
  • pressure (0–1, Standard 0), tangentialPressure (-1–1, Standard 0)
  • tiltX, tiltY (-90–90, Standard 0), twist (0–359, Standard 0)
  • altitudeAngle, azimuthAngle (Bogenmaß)
  • coalescedEvents, predictedEvents (PointerEvent[], Standard [])

Rückgabewert

Typ
PointerEvent
Beschreibung
Ein neues PointerEvent-Objekt mit isTrusted === false. Es wird erst ausgelöst, wenn es an dispatchEvent() übergeben wird.

Beispiele

Stift-Ereignis erzeugen und Eigenschaften prüfen

const event = new PointerEvent('pointerdown', {
  pointerId: 7,
  pointerType: 'pen',
  isPrimary: true,
  pressure: 0.6,
  tiltX: 15,
  clientX: 120,
  clientY: 80,
  bubbles: true
});

console.log(event.type, event.pointerType, event.pressure);
console.log(event instanceof MouseEvent, event.isTrusted);
pointerdown pen 0.6 true false

Zeichen-Canvas im Test mit einem simulierten Strich ansteuern

const canvas = document.querySelector('canvas');
const points = [];

canvas.addEventListener('pointermove', (e) => {
  if (e.buttons & 1) points.push([e.offsetX, e.offsetY, e.pressure]);
});

const rect = canvas.getBoundingClientRect();
const fire = (type, x, y, buttons) =>
  canvas.dispatchEvent(new PointerEvent(type, {
    pointerId: 1,
    pointerType: 'mouse',
    isPrimary: true,
    clientX: rect.left + x,
    clientY: rect.top + y,
    buttons,
    pressure: buttons ? 0.5 : 0,
    bubbles: true
  }));

fire('pointerdown', 10, 10, 1);
for (let x = 20; x <= 50; x += 10) fire('pointermove', x, 10, 1);
fire('pointerup', 50, 10, 0);

console.log(points.length);
4

Echte von synthetischen Ereignissen unterscheiden

const button = document.querySelector('#draw');

const onDown = (e) => {
  if (!e.isTrusted) {
    console.log('Simuliert:', e.pointerType);
    return;
  }
  console.log('Echte Eingabe');
};

button.addEventListener('pointerdown', onDown);
button.dispatchEvent(new PointerEvent('pointerdown', { pointerType: 'touch' }));
button.removeEventListener('pointerdown', onDown);
Simuliert: touch

// Wichtig · Fallstricke

  • bubbles ist standardmäßig false. Ohne bubbles: true erreicht das Ereignis delegierte Listener an Elternelementen nicht. Echte Pointer-Ereignisse steigen dagegen auf, abgesehen von pointerenter/pointerleave.
  • Synthetische Ereignisse lösen keine Folgeereignisse aus. Es entstehen weder kompatible Mausereignisse (mousedown, mouseup) noch ein click. Die Standardaktion bleibt ebenfalls aus. Wer das braucht, muss diese Ereignisse selbst auslösen.
  • setPointerCapture(pointerId) funktioniert nur mit der ID eines aktiven echten Zeigers. Bei ausgedachten IDs wirft es eine NotFoundError-DOMException.
  • offsetX/offsetY lassen sich nicht direkt setzen. Sie werden beim Auslösen aus clientX/clientY berechnet.
  • Wird pressure nicht gesetzt, ist der Wert 0, auch wenn Tasten gedrückt sind. Bei echten Mausereignissen mit gedrückter Taste beträgt er 0.5.
  • altitudeAngle, azimuthAngle, coalescedEvents und predictedEvents im Init-Objekt sind neuer und werden nicht in allen Browsern unterstützt.
  • Kompatibilität: In allen aktuellen Browsern verfügbar (Safari ab 13). In jsdom fehlte PointerEvent lange; dort ist eventuell ein Polyfill oder MouseEvent als Ersatz nötig.

Siehe auch

PointerEvent new MouseEvent() EventTarget.prototype.dispatchEvent() Element.prototype.setPointerCapture() PointerEvent.prototype.getCoalescedEvents() Event.isTrusted new BeforeInstallPromptEvent()
← Vorheriger Eintrag new PictureInPictureEvent()