CSSTranslate.y — Eigenschaft · JavaScript-Referenz

Signatur

CSSTranslate.y

Beschreibung

Die Eigenschaft y gehört zur Schnittstelle CSSTranslate aus dem CSS Typed Object Model (Houdini). Ein CSSTranslate-Objekt steht für die CSS-Funktionen translate(), translateY() oder translate3d(). Über y greifst du direkt auf die vertikale Verschiebung zu, ohne den transform-String selbst zerlegen zu müssen.

Der Wert ist ein CSSNumericValue, meist ein CSSUnitValue wie CSS.px(20) oder CSS.percent(50). Möglich ist auch ein CSSMathValue (etwa CSSMathSum für calc(50% + 10px)). Du kannst y auch neu zuweisen. Der neue Wert muss dann zum CSS-Typ <length-percentage> passen, sonst wirft der Browser einen TypeError.

Typische Einsatzfälle sind Animationen und Interaktionen, bei denen die Verschiebung eines Elements laufend neu berechnet wird, zum Beispiel bei Parallax-Effekten, Drag & Drop oder Scroll-Effekten. Mit Typed OM entfällt dabei das fehleranfällige Zusammensetzen und Auslesen von Strings.

Parameter

Name	Typ	Default	Beschreibung
$wert (beim Setzen)	CSSNumericValue		Neue vertikale Verschiebung. Erlaubt ist nur ein Wert vom Typ `<length-percentage>`, z. B. `CSS.px(12)`, `CSS.rem(1)`, `CSS.percent(-50)` oder eine `calc()`-Mischung als `CSSMathValue`.

Rückgabewert

Typ

CSSNumericValue

Beschreibung

Die aktuelle Verschiebung entlang der y-Achse, meist als CSSUnitValue mit value und unit.

Beispiele

y-Wert auslesen

const verschiebung = new CSSTranslate(CSS.px(10), CSS.px(20));

console.log(verschiebung.y.value); // Zahl
console.log(verschiebung.y.unit);  // Einheit
console.log(verschiebung.toString());

20 px translate(10px, 20px)

y-Wert ändern und aufs Element anwenden

const box = document.querySelector('.box');
const verschiebung = new CSSTranslate(CSS.px(0), CSS.px(0));

// Element um die halbe eigene Höhe nach oben schieben
verschiebung.y = CSS.percent(-50);

box.attributeStyleMap.set('transform', new CSSTransformValue([verschiebung]));
console.log(box.style.transform);

translate(0px, -50%)

Parallax-Effekt beim Scrollen

const hero = document.querySelector('.hero-bild');
const translate = new CSSTranslate(CSS.px(0), CSS.px(0));
const transform = new CSSTransformValue([translate]);

window.addEventListener('scroll', () => {
  // Bild bewegt sich mit 30 % der Scrollgeschwindigkeit
  translate.y = CSS.px(window.scrollY * 0.3);
  hero.attributeStyleMap.set('transform', transform);
}, { passive: true });

Ungültigen Wert abfangen

const t = new CSSTranslate(CSS.px(0), CSS.px(0));

try {
  t.y = CSS.deg(45); // Winkel ist keine Länge
} catch (err) {
  console.log(err.name);
}

console.log(t.y.toString()); // unverändert

TypeError 0px

// Wichtig · Fallstricke

Browser-Kompatibilität: CSS Typed OM gibt es in Chromium-Browsern ab Version 66 und in Safari ab 16.4. Firefox unterstützt es derzeit nicht. Prüfe die Unterstützung vorher, z. B. mit if ('CSSTranslate' in window), und sieh bei Bedarf einen Fallback über element.style.transform vor.
Typprüfung: Werte ohne Längen- oder Prozentbezug wie CSS.number(5) oder CSS.deg(45) lösen einen TypeError aus. Eine einfache Zahl wird nicht automatisch in px umgerechnet.
Keine Live-Bindung: Wenn du y änderst, ändert sich das Element noch nicht. Du musst den CSSTransformValue danach erneut mit attributeStyleMap.set() zuweisen.
Prozentwerte beziehen sich bei translate auf die Höhe der eigenen Rahmenbox (Border-Box) des Elements, nicht auf die des Elternelements.
Du kannst y auch dann setzen, wenn das Objekt aus translateX() entstanden ist. Die Ausgabe von toString() wird dann zu translate(x, y).

Siehe auch

CSSTranslate CSSTranslate.x CSSTranslate.z CSSTransformValue CSSNumericValue CSSUnitValue