MouseEvent.offsetY — Eigenschaft · JavaScript-Referenz

Signatur

MouseEvent.offsetY

Beschreibung

Die schreibgeschützte Eigenschaft offsetY eines MouseEvent gibt an, wie weit der Mauszeiger vertikal von der oberen Padding-Kante des Zielknotens (event.target) entfernt ist. Der Wert wird in CSS-Pixeln angegeben und ist ein double, kann also Nachkommastellen haben.

Typische Einsatzgebiete sind Zeichenflächen (<canvas>), eigene Schieberegler, Bildausschnitte, Heatmaps oder Tooltips, die direkt an der Mausposition innerhalb eines Elements erscheinen sollen. Weil sich der Wert auf das Element selbst bezieht, muss man Scroll-Positionen oder die Lage des Elements im Dokument nicht selbst herausrechnen.

Wichtig: Bezugspunkt ist immer event.target – also das innerste Element unter dem Mauszeiger, nicht unbedingt das Element, an dem der Listener hängt (event.currentTarget). Hat ein Container Kindelemente, springt offsetY beim Überfahren eines Kindes auf dessen Koordinatensystem um. Für stabile Werte relativ zum Container berechnet man die Position besser über clientY - currentTarget.getBoundingClientRect().top.

Auch PointerEvent und WheelEvent erben die Eigenschaft, da sie von MouseEvent abgeleitet sind.

Rückgabewert

Typ

number

Beschreibung

Vertikaler Abstand des Mauszeigers zur oberen Padding-Kante von event.target in CSS-Pixeln (double). Kann negativ sein, wenn der Zeiger über dem Rahmen (Border) liegt.

Beispiele

Mausposition in einem Canvas anzeigen

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

canvas.addEventListener('click', (event) => {
  const x = event.offsetX;
  const y = event.offsetY;
  console.log(`Klick bei x=${x}, y=${y}`);

  // Kleinen Punkt an der Klickposition zeichnen
  ctx.beginPath();
  ctx.arc(x, y, 4, 0, Math.PI * 2);
  ctx.fill();
});

Klick bei x=120, y=45

Vertikaler Schieberegler (Lautstärke) per Klick setzen

const regler = document.querySelector('.lautstaerke'); // enthält keine Kindelemente

regler.addEventListener('pointerdown', (event) => {
  const hoehe = regler.clientHeight;
  // Oben = 100 %, unten = 0 %
  const anteil = 1 - event.offsetY / hoehe;
  const prozent = Math.round(Math.min(Math.max(anteil, 0), 1) * 100);
  console.log(`Lautstärke: ${prozent} %`);
});

Lautstärke: 73 %

Robuste Alternative bei Containern mit Kindelementen

const karte = document.querySelector('.karte');

karte.addEventListener('mousemove', (event) => {
  // offsetY bezieht sich auf event.target – evtl. ein Kind-Element!
  const rect = event.currentTarget.getBoundingClientRect();
  const yRelativ = event.clientY - rect.top - event.currentTarget.clientTop;

  console.log('offsetY:', event.offsetY, '| relativ zum Container:', yRelativ);
});

offsetY: 12 | relativ zum Container: 212

// Wichtig · Fallstricke

Bezug auf target: Bei verschachtelten Elementen ändert sich das Koordinatensystem, sobald der Zeiger ein Kindelement überfährt. Abhilfe: pointer-events: none für Kinder oder Berechnung über getBoundingClientRect().
CSS-Transformationen: Bei transform (z. B. scale, rotate) liefern Browser offsetY im untransformierten lokalen Koordinatensystem – bei getBoundingClientRect() dagegen im transformierten Viewport-Raum. Nicht mischen.
Canvas-Skalierung: Ist die CSS-Größe eines Canvas ungleich seiner Pixelauflösung (canvas.height), muss man umrechnen: y * canvas.height / canvas.clientHeight.
Nachkommastellen: Laut Spezifikation ein double; ältere Browser lieferten Ganzzahlen. Bei Bedarf mit Math.round() runden.
Border: Bezugspunkt ist die Padding-Kante, nicht die Border-Kante – über dem oberen Rahmen sind negative Werte möglich.
Kompatibilität: In allen modernen Browsern verfügbar; Firefox unterstützt die Eigenschaft seit Version 39. Bei synthetisch erzeugten Ereignissen (new MouseEvent()) wird der Wert aus clientY und dem Ziel berechnet, nicht direkt übergeben.

Siehe auch

MessageEvent.ports MouseEvent.offsetX MouseEvent.altKey MouseEvent.clientY MouseEvent.layerY