CSSRotate.z — Eigenschaft · JavaScript-Referenz

Signatur

CSSRotate.z

Beschreibung

Die Eigenschaft z gehört zum Interface CSSRotate aus dem CSS Typed Object Model. Ein CSSRotate-Objekt steht für die CSS-Transformationsfunktionen rotate(), rotateX(), rotateY(), rotateZ() und rotate3d(). Die Rotationsachse wird durch einen Vektor (x, y, z) beschrieben; z ist dessen dritte Komponente.

Beim Lesen gibt z ein CSSNumericValue zurück, in der Regel ein CSSUnitValue mit der Einheit "number". Den reinen Zahlenwert erhält man über .value. Beim Schreiben kannst du eine einfache Zahl oder ein CSSNumericValue übergeben, etwa CSS.number(0.5). Der Wert muss einheitenlos sein, also dem CSS-Typ <number> entsprechen.

Wird ein CSSRotate nur mit einem Winkel erzeugt (new CSSRotate(angle)), handelt es sich um eine 2D-Drehung. Dann gilt x = 0, y = 0, z = 1 und is2D ist true. Die Eigenschaft ist vor allem nützlich, um 3D-Rotationen gezielt zu verändern, ohne Strings zu parsen. Ein Beispiel sind Animationen, bei denen sich die Drehachse schrittweise verschiebt.

Parameter

Name	Typ	Default	Beschreibung
$value (Setter) Pflicht	number \| CSSNumericValue		Neue z-Komponente der Rotationsachse. Muss einheitenlos sein (Typ `<number>`), z. B. `0.5` oder `CSS.number(0.5)`. Bei einer Einheit wie `CSS.px(1)` wird ein `TypeError` ausgelöst.

Rückgabewert

Typ

CSSNumericValue

Beschreibung

Die z-Komponente des Achsenvektors, meist ein CSSUnitValue mit unit: "number". Bei 2D-Rotationen ist der Wert 1.

Beispiele

3D-Rotation erzeugen und z auslesen

const rotation = new CSSRotate(0, 0, 1, CSS.deg(45));

console.log(rotation.z.value);   // reiner Zahlenwert
console.log(rotation.z.unit);    // Einheit des Wertes
console.log(rotation.toString());

1 number rotate3d(0, 0, 1, 45deg)

Standardwerte bei einer 2D-Rotation

const flat = new CSSRotate(CSS.deg(90));

console.log(flat.x.value, flat.y.value, flat.z.value);
console.log(flat.is2D);
console.log(flat.toString());

0 0 1 true rotate(90deg)

Drehachse eines Elements zur Laufzeit ändern

const box = document.querySelector('.box');

const rotation = new CSSRotate(CSS.number(1), CSS.number(1), CSS.number(0), CSS.deg(30));
box.attributeStyleMap.set('transform', new CSSTransformValue([rotation]));

// Später: Achse Richtung z kippen
const transform = box.attributeStyleMap.get('transform');
const rot = transform[0];
rot.z = 1;  // Zahl wird automatisch in CSSUnitValue umgewandelt
box.attributeStyleMap.set('transform', transform);

console.log(box.style.transform);

rotate3d(1, 1, 1, 30deg)

Ungültiger Wert mit Einheit

const rotation = new CSSRotate(0, 1, 0, CSS.deg(20));

try {
  rotation.z = CSS.px(2);
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

Browser-Kompatibilität: Das CSS Typed OM (und damit CSSRotate) wird in Chromium-Browsern ab Version 66 und in Safari ab 16.4 unterstützt. Firefox unterstützt es derzeit nicht. Prüfe die Verfügbarkeit mit 'CSSRotate' in window und sieh bei Bedarf eine String-basierte Alternative vor.
Rückgabetyp ist kein number: Auch wenn du eine Zahl zuweist, liefert der Getter ein CSSUnitValue zurück. Vergleiche wie rotation.z === 1 sind daher immer false. Verwende stattdessen rotation.z.value.
2D-Rotationen: Ist is2D gleich true, wird das Objekt als rotate(angle) in Text umgewandelt, und die Achsenwerte werden dabei ignoriert. Wenn du z änderst, setze is2D = false, damit die Änderung wirkt.
Nullvektor: Sind x, y und z alle 0, ist die Achse undefiniert. Die Transformation erzeugt dann keine sichtbare Drehung.
Änderungen am CSSRotate-Objekt wirken sich nicht automatisch auf das Element aus. Die Transformation muss erneut per attributeStyleMap.set() gesetzt werden.

Siehe auch

CSSRotate CSSRotate.x CSSRotate.y CSSRotate.angle CSSTransformComponent.is2D CSSTransformValue CSSUnitValue