MouseEvent.layerY — Eigenschaft · JavaScript-Referenz

Signatur

MouseEvent.layerY

Beschreibung

Die schreibgeschützte Eigenschaft MouseEvent.layerY gibt die vertikale Koordinate des Ereignisses relativ zur aktuellen Ebene als ganze Zahl in CSS-Pixeln zurück. Als Ebene gilt das Zielelement selbst, wenn es positioniert ist (position ungleich static), sonst der nächste positionierte Vorfahre. Gibt es keinen, wird relativ zur Seite gemessen. Das Scrollen innerhalb der Ebene wird dabei mitgerechnet.

Die Eigenschaft stammt aus der Netscape-Zeit und gehört zu keinem Standard. Sie funktioniert in allen modernen Browsern, ihr Verhalten ist aber nicht einheitlich festgelegt. In neuem Code solltest du stattdessen die standardisierten Eigenschaften nehmen:

offsetY – relativ zur Innenabstandskante (Padding-Kante) des Zielelements,
clientY – relativ zum sichtbaren Bereich des Fensters (Viewport),
pageY – relativ zum gesamten Dokument.

layerY ist deshalb vor allem beim Pflegen von altem Code wichtig. Oft taucht es auch als Rückfall-Lösung neben offsetY auf, zum Beispiel beim Zeichnen auf einem <canvas>, das selbst positioniert ist.

Rückgabewert

Typ

number

Beschreibung

Ganzzahlige vertikale Koordinate in CSS-Pixeln, gemessen relativ zur aktuellen Ebene (positioniertes Element oder Seite).

Beispiele

Koordinaten beim Klick ausgeben

const box = document.querySelector('#box');
box.style.position = 'relative'; // Box wird zur Ebene

box.addEventListener('click', (event) => {
  console.log(`layerY: ${event.layerY}, offsetY: ${event.offsetY}`);
});

layerY: 42, offsetY: 42

Unterschied zu clientY und pageY bei gescrollter Seite

document.addEventListener('mousemove', (event) => {
  const { clientY, pageY, layerY } = event;
  document.title = `client ${clientY} | page ${pageY} | layer ${layerY}`;
});

client 120 | page 920 | layer 920

Zeichnen auf einem Canvas mit Rückfall-Lösung

const canvas = document.querySelector('canvas');
canvas.style.position = 'relative';
const ctx = canvas.getContext('2d');

canvas.addEventListener('mousedown', (event) => {
  // Standard zuerst, layerY nur als Rückfall für alte Umgebungen
  const y = event.offsetY ?? event.layerY;
  const x = event.offsetX ?? event.layerX;
  ctx.fillRect(x - 2, y - 2, 4, 4);
});

// Wichtig · Fallstricke

Nicht standardisiert: layerY steht in keiner W3C- oder WHATWG-Spezifikation. Die Browser unterstützen es zwar, Randfälle wie Transformationen, Rahmen oder verschachtelte Scroll-Container behandeln sie aber teils unterschiedlich.
Das Ergebnis hängt vom CSS-position-Wert der Vorfahren ab. Ändert sich das Layout, zum Beispiel wenn ein Elternelement position: relative bekommt, ändert sich auch der Bezugspunkt.
Rahmen (border) werden anders verrechnet als bei offsetY. Die beiden Werte können deshalb um die Rahmenbreite voneinander abweichen.
CSS-Transformationen wie transform: scale() werden nicht berücksichtigt. Für genaue Werte rechne mit clientY - element.getBoundingClientRect().top.
Bei synthetischen Ereignissen, die mit new MouseEvent() erzeugt werden, ist layerY in der Regel 0, weil sich der Wert im Konstruktor nicht setzen lässt.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird ohne Fehlermeldung ignoriert.

Siehe auch

MouseEvent.layerX MouseEvent.offsetY MouseEvent.clientY MouseEvent.pageY MouseEvent.screenY MouseEvent Element.getBoundingClientRect()