CSSScale.y — Eigenschaft · JavaScript-Referenz

Signatur

CSSScale.y

Beschreibung

Die Eigenschaft y des Interfaces CSSScale steht für die y-Komponente des Skalierungsvektors, also den Faktor, mit dem ein Element vertikal gestreckt oder gestaucht wird. Sie entspricht dem zweiten Argument der CSS-Funktion scale(x, y) bzw. scale3d(x, y, z). Ein Wert von 1 lässt die Höhe unverändert, 2 verdoppelt sie, 0.5 halbiert sie, und negative Werte spiegeln das Element an der x-Achse.

Die Eigenschaft ist Teil des CSS Typed OM. Statt mit Strings wie "scale(1, 2)" zu arbeiten, bekommst du einen typisierten Wert (meist einen CSSUnitValue mit der Einheit "number"), den du direkt auslesen und verändern kannst, ohne Strings zusammenzubauen oder zu zerlegen. Das ist vor allem bei Animationen und interaktiven Transformationen praktisch, bei denen Werte häufig neu berechnet werden.

Beim Setzen nimmt y entweder eine einfache Zahl an, die intern in CSS.number() umgewandelt wird, oder einen CSSNumericValue, der zum Typ „Zahl“ auflösen muss (z. B. CSS.number(2) oder ein CSSMathSum aus Zahlen). Werte mit Längen- oder Winkeleinheiten wie CSS.px(10) sind nicht erlaubt.

Hinweis: MDN beschreibt y teilweise als „Ordinate des Übertragungsvektors“. Gemeint ist der Skalierungsvektor, denn mit Verschiebung (CSSTranslate) hat die Eigenschaft nichts zu tun.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	number \| CSSNumericValue		Nur beim Setzen: neuer Skalierungsfaktor für die y-Achse. Muss einheitenlos sein, also eine Zahl oder ein `CSSNumericValue` vom Typ „Zahl“.

Rückgabewert

Typ

CSSNumericValue

Beschreibung

Der aktuelle y-Skalierungsfaktor, typischerweise ein CSSUnitValue mit unit === "number". Den reinen Zahlenwert bekommst du über .value.

Beispiele

y-Faktor auslesen

const scale = new CSSScale(1.5, 2);

console.log(scale.y instanceof CSSUnitValue);
console.log(scale.y.value, scale.y.unit);
console.log(scale.toString());

true 2 "number" scale(1.5, 2)

y-Faktor setzen (Zahl oder CSS.number)

const scale = new CSSScale(1, 1);

// Einfache Zahl wird automatisch umgewandelt
scale.y = 0.5;
console.log(scale.toString());

// Oder explizit typisiert
scale.y = CSS.number(-1); // vertikal spiegeln
console.log(scale.toString());

scale(1, 0.5) scale(1, -1)

Element beim Scrollen vertikal stauchen

const header = document.querySelector('header');
const scale = new CSSScale(1, 1);
header.attributeStyleMap.set('transform', new CSSTransformValue([scale]));

window.addEventListener('scroll', () => {
  // Von 1 bis 0.6 stauchen, abhängig von der Scrollposition
  const factor = Math.max(0.6, 1 - window.scrollY / 500);
  scale.y = CSS.number(factor);
  // Transform-Wert neu setzen, damit die Änderung übernommen wird
  header.attributeStyleMap.set('transform', new CSSTransformValue([scale]));
}, { passive: true });

Ungültige Einheit führt zu TypeError

const scale = new CSSScale(1, 1);

try {
  scale.y = CSS.px(10);
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

Nur einheitenlose Werte: Wenn du Werte mit Einheiten zuweist (CSS.px(), CSS.deg(), CSS.percent() usw.), wird ein TypeError ausgelöst. Prozentangaben wie in scale: 50% musst du vorher in Faktoren umrechnen (0.5).
Keine automatische Übernahme: Wenn du y an einem eigenständigen CSSScale-Objekt änderst, ändert sich das Element nicht automatisch. Du musst den CSSTransformValue danach wieder per attributeStyleMap.set() zuweisen.
Berechnete Werte: element.computedStyleMap().get('transform') gibt oft eine Matrix zurück (CSSMatrixComponent) und kein CSSScale. Für den direkten Zugriff auf y solltest du attributeStyleMap oder selbst erzeugte Werte verwenden.
Browser-Kompatibilität: CSS Typed OM wird von Chromium-Browsern (Chrome, Edge, Opera, ab Version 66) und von Safari ab 16.4 unterstützt. Firefox unterstützt es nicht. Prüfe die Unterstützung mit 'CSSScale' in window und setze sonst als Ausweichlösung element.style.transform mit einem String.

Siehe auch

CSSMathValue.operator CSSScale.x CSSScale.z CSSRotate.y CSSRotate.x