MouseEvent.screenY — Eigenschaft · JavaScript-Referenz

Signatur

MouseEvent.screenY

Beschreibung

MouseEvent.screenY gibt die vertikale Koordinate des Mauszeigers relativ zur oberen Kante des gesamten Bildschirms bzw. des virtuellen Desktops zurück. Anders als bei clientY (relativ zum Viewport) oder pageY (relativ zum Dokument) spielen Scrollposition, Fensterposition und Browser-Oberfläche keine Rolle. Der Wert gilt für den Zeitpunkt, an dem das Ereignis ausgelöst wurde.

Die Eigenschaft ist dann nützlich, wenn eine Position fensterübergreifend gebraucht wird, z. B. um ein Popup mit window.open() an der Klickstelle zu öffnen, Positionen zwischen mehreren Fenstern abzugleichen oder zusammen mit window.screenY und screen.availHeight zu rechnen. Für die Positionierung von Elementen innerhalb der Seite sind clientY, pageY oder offsetY fast immer die bessere Wahl.

Weil PointerEvent, WheelEvent und DragEvent von MouseEvent erben, gibt es screenY auch dort. Der Wert ist ein double in CSS-Pixeln. Ältere Spezifikationen haben ihn als ganze Zahl (long) definiert, deshalb liefern manche Browser Nachkommastellen, andere nicht.

Rückgabewert

Typ

number

Beschreibung

Vertikaler Abstand des Mauszeigers zur oberen Bildschirmkante in CSS-Pixeln. Auf Systemen mit mehreren Monitoren kann der Wert negativ sein oder größer als screen.height.

Beispiele

Koordinatensysteme vergleichen

document.addEventListener('click', (event) => {
  console.log(`screenY: ${event.screenY}`); // relativ zum Bildschirm
  console.log(`clientY: ${event.clientY}`); // relativ zum Viewport
  console.log(`pageY:   ${event.pageY}`);   // relativ zum Dokument
});

screenY: 612 clientY: 480 pageY: 1280

Popup an der Klickposition öffnen

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

button.addEventListener('click', (event) => {
  const breite = 320;
  const hoehe = 240;
  // screenX/screenY passen direkt zu den Fensterkoordinaten von window.open
  const links = Math.round(event.screenX);
  const oben = Math.round(event.screenY);
  window.open(
    '/hilfe.html',
    'hilfe',
    `width=${breite},height=${hoehe},left=${links},top=${oben}`
  );
});

Vertikale Ziehstrecke unabhängig vom Scrollen messen

let startY = null;

const onMove = (event) => {
  const delta = event.screenY - startY;
  console.log(`Gezogen: ${delta.toFixed(1)} px`);
};

const onUp = () => {
  document.removeEventListener('pointermove', onMove);
  document.removeEventListener('pointerup', onUp);
  startY = null;
};

document.addEventListener('pointerdown', (event) => {
  startY = event.screenY;
  document.addEventListener('pointermove', onMove);
  document.addEventListener('pointerup', onUp);
});

Gezogen: 42.0 px

// Wichtig · Fallstricke

Mehrere Monitore: Liegt ein Monitor über dem Hauptbildschirm, sind negative Werte möglich. Außerdem kann screenY größer als screen.height sein. Den Wertebereich also nicht als begrenzt annehmen.
Zoom und Gerätepixel: Der Wert ist in CSS-Pixeln angegeben, nicht in physischen Pixeln. Bei Seitenzoom oder hohem devicePixelRatio weicht er von den Pixeln des Betriebssystems ab.
Datenschutz: Browser wie Firefox (mit privacy.resistFingerprinting) oder Tor verfälschen oder runden Bildschirmkoordinaten absichtlich, um Fingerprinting zu erschweren. Die Werte sollten deshalb nicht für sicherheitsrelevante Logik verwendet werden.
Synthetische Ereignisse: Bei new MouseEvent('click') ohne passendes Init-Objekt ist screenY gleich 0. Setzen lässt sich der Wert nur über { screenY: … } im Konstruktor, denn die Eigenschaft ist schreibgeschützt.
Touch: Bei aus Touch-Eingaben abgeleiteten Mausereignissen und bei Touch.screenY kann der Wert je nach Browser abweichen. Für einheitliches Verhalten besser PointerEvent verwenden.
Wird von allen gängigen Browsern seit Jahren unterstützt. Nachkommastellen (double) liefern nur neuere Engines.

Siehe auch

MouseEvent.screenX MouseEvent.clientY MouseEvent.pageY MouseEvent.offsetY MouseEvent.movementY Window.screenY MouseEvent