MouseEvent.layerX — Eigenschaft · JavaScript-Referenz

Signatur

MouseEvent.layerX

Beschreibung

MouseEvent.layerX gibt die horizontale Koordinate eines Mausereignisses als ganze Zahl in CSS-Pixeln zurück. Gemessen wird relativ zur sogenannten aktuellen Ebene. Die Eigenschaft ist schreibgeschützt und stammt noch aus der Zeit von Netscape. Damals wurden mit „Layer“ positionierte Ebenen bezeichnet.

Wie der Bezugspunkt bestimmt wird:

Liegt das Zielelement in einem positionierten Element oder ist es selbst positioniert (position: relative, absolute, fixed oder sticky), bezieht sich der Wert auf die linke obere Ecke dieses Elements.
Andernfalls bezieht sich der Wert auf das gesamte Dokument. Das Scrollen der Seite wird dabei eingerechnet, der Wert entspricht dann ungefähr pageX.

Anzutreffen ist layerX vor allem in älterem Code, zum Beispiel in Zeichen- oder Canvas-Anwendungen, in denen die Position innerhalb eines Containers gebraucht wird. In neuem Code solltest du die standardisierten Eigenschaften offsetX, clientX oder pageX verwenden oder die Position selbst mit getBoundingClientRect() ausrechnen.

Rückgabewert

Typ

number

Beschreibung

Ganze Zahl in CSS-Pixeln: die horizontale Position relativ zum nächsten positionierten Element, ersatzweise zum Dokument.

Beispiele

Mausposition in einem positionierten Container ausgeben

// HTML: <div id="box" style="position: relative; width: 300px; height: 200px;"></div>
const box = document.getElementById('box');

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

layerX: 42, layerY: 17 (je nach Mausposition)

layerX mit offsetX, clientX und pageX vergleichen

document.addEventListener('click', (event) => {
  console.table({
    layerX: event.layerX,   // relativ zum nächsten positionierten Vorfahren
    offsetX: event.offsetX, // relativ zur Padding-Kante des Zielelements
    clientX: event.clientX, // relativ zum Viewport
    pageX: event.pageX      // relativ zum Dokument (inklusive Scrollen)
  });
});

Tabelle mit den vier Werten. Ohne positionierten Vorfahren gilt layerX ≈ pageX.

Standardkonforme Alternative mit Rückfallwert

const getLocalX = (event, element) => {
  const rect = element.getBoundingClientRect();
  // Standardweg: Viewport-Koordinate minus linke Kante des Elements
  return Math.round(event.clientX - rect.left);
};

const canvas = document.querySelector('canvas');
canvas.addEventListener('pointerdown', (event) => {
  const x = getLocalX(event, canvas);
  const legacy = event.layerX ?? x; // nur zum Vergleich
  console.log({ x, legacy });
});

{ x: 120, legacy: 120 } (bei positioniertem Canvas ohne Rahmen)

// Wichtig · Fallstricke

Nicht standardisiert: layerX steht in keiner W3C- oder WHATWG-Spezifikation. Die aktuellen Browser unterstützen die Eigenschaft zwar, das Verhalten in Randfällen kann sich aber unterscheiden, etwa bei Rahmen (border), CSS-Transformationen oder Elementen, die scrollen.
Bezugspunkt ändert sich still: Wird einem Vorfahren position: relative hinzugefügt oder entfernt, liefert layerX plötzlich ganz andere Werte, obwohl sich am JavaScript nichts geändert hat.
Nicht dasselbe wie offsetX: offsetX bezieht sich immer auf das Zielelement (event.target), layerX dagegen auf den positionierten Vorfahren.
Bei Touch- oder Tastatureingaben ohne Mausposition ist der Wert oft 0. Verlässliche Werte über alle Eingabegeräte hinweg bekommst du mit Pointer-Events und clientX zusammen mit getBoundingClientRect().
Die Eigenschaft ist schreibgeschützt. Zuweisungen werden stillschweigend ignoriert.

Siehe auch

MouseEvent.layerY MouseEvent.offsetX MouseEvent.clientX MouseEvent.pageX MouseEvent.screenX Element.getBoundingClientRect() MouseEvent