CSSScale.z — Eigenschaft · JavaScript-Referenz

Signatur

CSSScale.z

Beschreibung

CSSScale.z gehört zur CSS Typed Object Model API und steht für die z-Komponente des Skalierungsvektors einer Transformation. In MDN heißt es an dieser Stelle „Translationsvektor“. Das ist ein Kopierfehler von CSSTranslate, denn bei CSSScale geht es immer um Skalierungsfaktoren. Der Wert ist dimensionslos: 1 lässt die Größe unverändert, 2 verdoppelt die Tiefe, 0.5 halbiert sie.

Beim Lesen bekommst du einen CSSNumericValue zurück, meistens einen CSSUnitValue mit der Einheit "number". Beim Schreiben kannst du eine einfache Zahl (number) oder einen CSSNumericValue übergeben. Eine Zahl wird automatisch in CSSUnitValue(n, "number") umgewandelt.

Die Eigenschaft ist nur bei 3D-Skalierungen wichtig. Wenn du new CSSScale(x, y) ohne dritten Parameter aufrufst, wird z auf 1 gesetzt und is2D ist true. Solange is2D den Wert true hat, wird z bei der Serialisierung (toString()) und in toMatrix() ignoriert.

Typische Anwendungsfälle: Transformationen per Skript lesen und ändern, ohne CSS-Strings zu parsen, zum Beispiel in Animationsschleifen, 3D-Karteneffekten oder CSS-Houdini-Worklets.

Parameter

Name	Typ	Default	Beschreibung
$wert (beim Setzen) Pflicht	number \| CSSNumericValue	1	Neuer Skalierungsfaktor für die z-Achse. Der Wert muss zum CSS-Typ `<number>` passen, also ohne Einheit wie `px` oder `%`. Zahlen werden automatisch in `CSSUnitValue` mit der Einheit `"number"` umgewandelt.

Rückgabewert

Typ

CSSNumericValue

Beschreibung

Der aktuelle z-Skalierungsfaktor, meistens ein CSSUnitValue mit unit === "number". Bei berechneten Ausdrücken kann es auch ein CSSMathValue sein (z. B. CSSMathSum).

Beispiele

z-Komponente einer 3D-Skalierung lesen

// 3D-Skalierung: x = 2, y = 2, z = 0.5
const scale = new CSSScale(2, 2, 0.5);

console.log(scale.z.value);   // Zahlenwert
console.log(scale.z.unit);    // Einheit
console.log(scale.is2D);      // 3D, weil z angegeben wurde
console.log(scale.toString());

0.5 number false scale3d(2, 2, 0.5)

Standardwert bei 2D-Skalierung

const flat = new CSSScale(1.5, 1.5);

console.log(flat.z.value); // Standardwert 1
console.log(flat.is2D);
console.log(flat.toString()); // z wird ignoriert

1 true scale(1.5, 1.5)

z-Tiefe eines Elements per Typed OM animieren

const card = document.querySelector('.card');
const scale = new CSSScale(1, 1, 1);
const transform = new CSSTransformValue([
  new CSSPerspective(CSS.px(600)),
  new CSSRotate(CSS.deg(30), CSS.deg(0), CSS.deg(0)),
  scale
]);

let t = 0;
const tick = () => {
  t += 0.05;
  // z-Faktor schwingt zwischen 0.5 und 1.5
  scale.z = 1 + Math.sin(t) * 0.5;
  card.attributeStyleMap.set('transform', transform);
  requestAnimationFrame(tick);
};
requestAnimationFrame(tick);

Ungültiger Typ beim Setzen

const scale = new CSSScale(1, 1, 2);

try {
  scale.z = CSS.px(10); // Längen sind keine gültigen Skalierungsfaktoren
} catch (err) {
  console.log(err.name);
}

scale.z = CSS.number(3); // korrekt
console.log(scale.toString());

TypeError scale3d(1, 1, 3)

// Wichtig · Fallstricke

Kein Translationsvektor: In der MDN-Beschreibung steht fälschlich „Translationsvektor“. z ist ein Skalierungsfaktor ohne Einheit.
TypeError: Wenn du einen Wert mit Einheit zuweist (z. B. CSS.px() oder CSS.percent()), wird ein TypeError ausgelöst. Nur Werte vom Typ <number> sind erlaubt.
is2D beachten: Wenn du z setzt, wird is2D nicht automatisch auf false umgestellt. Solange is2D === true gilt, hat der z-Wert keine Wirkung auf toString() und toMatrix(). Setze bei Bedarf scale.is2D = false.
Keine automatische Übernahme: Wenn du ein CSSScale-Objekt änderst, ändert sich das Element noch nicht. Du musst den Transformationswert erneut mit attributeStyleMap.set() zuweisen.
Browser-Kompatibilität: CSS Typed OM gibt es in Chromium-Browsern (Chrome und Edge ab Version 66) und in Safari ab 16.4. Firefox unterstützt die API bisher nicht. Prüfe deshalb vorher mit 'CSSScale' in window, ob sie verfügbar ist.
Ein z-Faktor von 0 macht das Element in der Tiefe flach. Ohne Perspektive und 3D-Rotation sieht man von einer z-Skalierung meistens nichts.

Siehe auch

CSSScale.x CSSScale.y CSSRotate.z CSSRotate.x CSSRotate.y