PointerEvent.getCoalescedEvents() — Methode · JavaScript-Referenz

Signatur

PointerEvent.prototype.getCoalescedEvents()

Beschreibung

Browser liefern pointermove-Ereignisse normalerweise höchstens einmal pro Bildaufbau (etwa 60 bis 120 Mal pro Sekunde). Eingabegeräte wie Grafiktabletts, Stifte oder Gaming-Mäuse melden ihre Position aber oft viel häufiger. Damit der Haupt-Thread nicht überlastet wird, fasst der Browser diese Zwischenpositionen zu einem einzigen Ereignis zusammen (Koaleszierung). Mit getCoalescedEvents() bekommst du genau diese Zwischenereignisse zurück.

Das ist vor allem für Zeichen- und Handschrift-Anwendungen wichtig: Wenn du nur die Koordinaten des gelieferten Ereignisses verwendest, werden schnelle Striche eckig, weil Punkte fehlen. Mit allen zusammengefassten Ereignissen entstehen glatte, genaue Linien, auch wenn Druck (pressure) und Neigung (tiltX/tiltY) sich ändern.

Jedes zurückgegebene Ereignis hat eigene Werte für clientX/clientY, pressure, timeStamp usw. Die zurückgegebenen Ereignisse sind nicht vertrauenswürdig ausgelöst (sie werden nicht verteilt, du kannst sie nur auslesen). Sie haben kein Ziel für eine Weiterleitung, target entspricht aber dem Ziel des übergeordneten Ereignisses. Bei anderen Ereignistypen als pointermove/pointerrawupdate ist das Array leer.

Rückgabewert

Typ

PointerEvent[]

Beschreibung

Ein Array von PointerEvent-Objekten in zeitlicher Reihenfolge. Das letzte Element entspricht im Normalfall dem übergeordneten Ereignis selbst. Bei Ereignistypen ohne Zusammenfassung, z. B. pointerdown, ist das Array leer. Bei vertrauenswürdig ausgelösten pointermove-Ereignissen enthält es mindestens einen Eintrag.

Beispiele

Glatte Linien auf einem Canvas zeichnen

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

canvas.addEventListener('pointerdown', (e) => {
  drawing = true;
  canvas.setPointerCapture(e.pointerId);
  ctx.beginPath();
  ctx.moveTo(e.offsetX, e.offsetY);
});

canvas.addEventListener('pointermove', (e) => {
  if (!drawing) return;
  // Fallback, falls die Methode nicht unterstützt wird
  const events = e.getCoalescedEvents?.() ?? [e];
  for (const ce of events) {
    ctx.lineTo(ce.offsetX, ce.offsetY);
  }
  ctx.stroke();
});

canvas.addEventListener('pointerup', () => {
  drawing = false;
});

Anzahl der zusammengefassten Ereignisse protokollieren

document.addEventListener('pointermove', (e) => {
  const coalesced = e.getCoalescedEvents();
  console.log(`${coalesced.length} Zwischenereignis(se) in diesem pointermove`);
  for (const ce of coalesced) {
    console.log(ce.clientX, ce.clientY, ce.timeStamp.toFixed(1));
  }
});

3 Zwischenereignis(se) in diesem pointermove 412 230 10523.4 415 233 10527.6 419 236 10531.8

Druckempfindlicher Stift mit variabler Strichstärke

const canvas = document.querySelector('#pad');
const ctx = canvas.getContext('2d');
let last = null;

canvas.addEventListener('pointermove', (e) => {
  if (e.buttons !== 1) { last = null; return; }
  for (const ce of e.getCoalescedEvents()) {
    if (last) {
      ctx.lineWidth = 1 + ce.pressure * 8; // Druck 0–1
      ctx.lineCap = 'round';
      ctx.beginPath();
      ctx.moveTo(last.x, last.y);
      ctx.lineTo(ce.offsetX, ce.offsetY);
      ctx.stroke();
    }
    last = { x: ce.offsetX, y: ce.offsetY };
  }
});

// Wichtig · Fallstricke

Browser-Kompatibilität: Chrome/Edge und Firefox unterstützen die Methode seit Längerem, Safari erst seit Version 18. Für ältere Browser prüfst du mit e.getCoalescedEvents?.() ?? [e] und nutzt sonst das Ereignis selbst.
Nur in einem sicheren Kontext (HTTPS) garantiert. In einigen Browsern ist die Methode über HTTP nicht verfügbar.
Die Methode liefert nur Daten für pointermove und pointerrawupdate. Bei pointerdown/pointerup ist das Array leer.
Rufe getCoalescedEvents() synchron im Handler auf. Das Array nicht zwischenspeichern und später erneut auslesen.
Bei new PointerEvent(...) selbst erzeugte Ereignisse enthalten nur die Einträge, die über die Option coalescedEvents übergeben wurden (sonst ist das Array leer).
Leistung: Viele Zwischenpunkte bedeuten mehr Zeichenarbeit. Bei aufwendigem Zeichnen die Punkte sammeln und gebündelt in requestAnimationFrame verarbeiten.
Für eine Vorhersage künftiger Positionen (weniger Verzögerung) gibt es ergänzend getPredictedEvents().

Siehe auch

PointerEvent PointerEvent.getPredictedEvents() PointerEvent.pressure Element.setPointerCapture() StorageEvent.initStorageEvent()