Signatur
Beschreibung
Die schreibgeschützte Eigenschaft clientY des MouseEvent-Interfaces gibt die vertikale Koordinate an, an der das Ereignis ausgelöst wurde, und zwar relativ zum Viewport, also zum sichtbaren Bereich des Browserfensters. Der Wert 0 entspricht der Oberkante des Viewports, egal wie weit die Seite gescrollt ist.
Damit unterscheidet sich clientY von pageY (relativ zum gesamten Dokument, also inklusive Scroll-Versatz), von screenY (relativ zum Bildschirm) und von offsetY (relativ zur Padding-Kante des Zielelements). clientY passt immer dann, wenn du mit viewportbezogenen Werten arbeitest, zum Beispiel mit Element.getBoundingClientRect(), position: fixed oder document.elementFromPoint(). Diese APIs nutzen dasselbe Koordinatensystem.
Da PointerEvent und DragEvent von MouseEvent erben, steht clientY auch bei pointermove, pointerdown, dragover usw. zur Verfügung. Touch-Ereignisse (TouchEvent) haben keine eigene clientY-Eigenschaft. Dort liest du den Wert pro Berührungspunkt über event.touches[i].clientY aus.
Rückgabewert
double und kann in modernen Browsern Nachkommastellen haben. Wurde das Ereignis synthetisch ohne Koordinaten erzeugt, ist er 0.Beispiele
Mausposition im Viewport anzeigen
const anzeige = document.querySelector('#position');
const beiBewegung = (event) => {
anzeige.textContent = `X: ${event.clientX}, Y: ${event.clientY}`;
};
document.addEventListener('mousemove', beiBewegung);
// Später wieder abmelden:
// document.removeEventListener('mousemove', beiBewegung);Klickposition relativ zu einem Element berechnen
const canvas = document.querySelector('canvas');
canvas.addEventListener('click', (event) => {
const rect = canvas.getBoundingClientRect();
// clientY und rect.top liegen beide im Viewport-Koordinatensystem
const y = event.clientY - rect.top;
const x = event.clientX - rect.left;
console.log(`Klick im Canvas bei ${Math.round(x)} / ${Math.round(y)}`);
});Kontextmenü an der Mausposition öffnen (position: fixed)
const menue = document.querySelector('#kontextmenue');
document.addEventListener('contextmenu', (event) => {
event.preventDefault();
const maxY = window.innerHeight - menue.offsetHeight;
// Nicht über den unteren Viewport-Rand hinausragen lassen
menue.style.top = `${Math.min(event.clientY, maxY)}px`;
menue.style.left = `${event.clientX}px`;
menue.hidden = false;
});clientY mit pageY vergleichen
document.addEventListener('click', (event) => {
console.log('clientY:', event.clientY);
console.log('pageY: ', event.pageY);
console.log('Scroll: ', window.scrollY);
// pageY === clientY + scrollY
});// Wichtig · Fallstricke
- Scrollen wird nicht berücksichtigt: Brauchst du dokumentbezogene Koordinaten, zum Beispiel für absolut positionierte Elemente in einer gescrollten Seite, nimm
pageYoder rechneclientY + window.scrollY. - Schreibgeschützt: Eine Zuweisung wie
event.clientY = 10bleibt wirkungslos. Für synthetische Ereignisse gibst du den Wert im Konstruktor an:new MouseEvent('click', { clientY: 10 }). - Nachkommastellen: Laut CSSOM View ist der Typ
double. Bei Zoom oder auf hochauflösenden Displays können deshalb Werte wie145.5vorkommen. Runde bei Bedarf mitMath.round(). - Touch: Bei
touchstart/touchmoveistevent.clientYundefined. Verwende stattdessenevent.touches[0].clientYoder gleich Pointer-Events. - iframes und CSS-Transformationen: Der Wert bezieht sich auf den Viewport des Dokuments, in dem das Ereignis auftritt. Transformationen (
transform: scale()) des Zielelements fließen nicht ein, diese musst du selbst herausrechnen. - Performance:
mousemovefeuert sehr häufig. Aufwendige DOM-Änderungen solltest du perrequestAnimationFrame()bündeln. - Kompatibilität: Wird von allen Browsern unterstützt, auch von sehr alten.