DOMRectReadOnly.y — Eigenschaft · JavaScript-Referenz

Signatur

DOMRectReadOnly.y

Beschreibung

Die Eigenschaft y gibt die vertikale Koordinate des Ursprungs eines Rechtecks zurück. Rechtecke dieser Art liefert zum Beispiel Element.getBoundingClientRect(). Dort bezieht sich der Wert auf den Viewport, also den sichtbaren Bereich des Fensters. Bei einem ResizeObserverEntry.contentRect ist der Wert dagegen relativ zur Padding-Box des beobachteten Elements.

Der Ursprung ist nicht immer die obere Kante. Ist die Höhe (height) negativ, dann liegt der Ursprung unten und y ist nicht gleich top. Wer sicher die obere Kante braucht, nimmt top. Das ist immer Math.min(y, y + height).

Bei DOMRectReadOnly lässt sich y nur lesen. Die abgeleitete Klasse DOMRect erlaubt dagegen auch das Schreiben. Typische Einsatzfälle sind Positionsberechnungen für Tooltips und Pop-ups, Kollisionsprüfungen, Scroll-Logik und die Ausrichtung von Elementen zueinander.

Rückgabewert

Typ

number

Beschreibung

Die y-Koordinate des Rechteck-Ursprungs in CSS-Pixeln (double). Sie kann auch Nachkommastellen haben oder negativ sein.

Beispiele

Rechteck direkt erzeugen und y auslesen

const rect = new DOMRectReadOnly(10, 40, 200, 100);
console.log(rect.y);   // Ursprung
console.log(rect.top); // obere Kante

// Schreiben hat keine Wirkung (im Strict Mode: TypeError)
rect.y = 99;
console.log(rect.y);

40 40 40

Negative Höhe: y ist nicht gleich top

const rect = DOMRectReadOnly.fromRect({ x: 0, y: 100, width: 50, height: -30 });
console.log(rect.y);      // Ursprung unten
console.log(rect.top);    // tatsächliche obere Kante
console.log(rect.bottom);

100 70 100

Tooltip unter einem Element platzieren

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

const positionTooltip = () => {
  const { x, y, height } = button.getBoundingClientRect();
  // Viewport-Koordinaten plus Scroll-Offset ergeben Dokument-Koordinaten
  tooltip.style.left = `${x + window.scrollX}px`;
  tooltip.style.top = `${y + height + window.scrollY + 8}px`;
};

button.addEventListener('mouseenter', positionTooltip);

Prüfen, ob ein Element oberhalb des Viewports liegt

const istUeberViewport = (el) => {
  const rect = el.getBoundingClientRect();
  return rect.y + rect.height < 0;
};

window.addEventListener('scroll', () => {
  const header = document.querySelector('header');
  document.body.classList.toggle('sticky-nav', istUeberViewport(header));
}, { passive: true });

// Wichtig · Fallstricke

Bezugssystem beachten: getBoundingClientRect().y bezieht sich auf den Viewport und ändert sich beim Scrollen. Für Koordinaten relativ zum Dokument muss man window.scrollY addieren.
y und top sind nicht dasselbe: Bei negativer Höhe unterscheiden sich die beiden Werte. Für die obere Kante verwendet man daher besser top.
Schreibschutz: Wer y zuweist, wird im normalen Modus ignoriert. Im Strict Mode (auch in ES-Modulen) wirft die Zuweisung einen TypeError. Für veränderbare Rechtecke gibt es DOMRect.
Keine Live-Werte: Das Rechteck ist ein Schnappschuss. Nach Änderungen am Layout muss man getBoundingClientRect() erneut aufrufen.
Performance: Wer getBoundingClientRect() häufig aufruft, etwa in Scroll-Handlern, kann ein erzwungenes Neuberechnen des Layouts (Reflow) auslösen. Oft ist IntersectionObserver die bessere Wahl.
Kompatibilität: Alte Versionen von Internet Explorer und Edge (vor der Chromium-Basis) kannten nur top und left, aber kein x und y. Alle modernen Browser unterstützen y.

Siehe auch

DOMRectReadOnly DOMRectReadOnly.x DOMRectReadOnly.top DOMRectReadOnly.height DOMRect Element.getBoundingClientRect() DOMRectReadOnly.fromRect()