CSSRotate.x — Eigenschaft · JavaScript-Referenz

Signatur

CSSRotate.x

Beschreibung

Die Eigenschaft x gehört zum Interface CSSRotate aus dem CSS Typed Object Model. Sie beschreibt die x-Koordinate des Richtungsvektors (x, y, z), um den ein Element gedreht wird. Zusammen mit y, z und angle entspricht ein CSSRotate-Objekt der CSS-Funktion rotate3d(x, y, z, angle).

Beim Lesen erhältst du ein CSSNumericValue, in der Praxis meist ein CSSUnitValue mit der Einheit "number". Den reinen Zahlenwert liest du über rot.x.value aus. Zum Schreiben kannst du eine einfache Zahl oder einen einheitenlosen numerischen Wert wie CSS.number(0.5) zuweisen.

Wenn du den Konstruktor nur mit einem Winkel aufrufst (new CSSRotate(angle)), entsteht eine 2D-Drehung. Dann ist x gleich 0, y gleich 0, z gleich 1 und is2D ist true. Brauchst du eine 3D-Drehung um eine beliebige Achse, gibst du beim Konstruktor alle vier Argumente an oder änderst x, y und z nachträglich.

Typische Einsatzfälle sind Animationen und interaktive 3D-Effekte. Hier änderst du die Drehachse per Skript, ohne Transform-Zeichenketten zusammenzubauen und wieder zu zerlegen.

Parameter

Name	Typ	Default	Beschreibung
$wert (beim Setzen)	number \| CSSNumericValue		Neuer x-Anteil der Drehachse. Er muss einheitenlos sein: eine Zahl oder z. B. `CSS.number(1)`. Werte mit Einheit wie `CSS.px(1)` lösen einen `TypeError` aus.

Rückgabewert

Typ

CSSNumericValue

Beschreibung

Ein numerischer Wert, meist ein CSSUnitValue mit unit === "number", für die x-Koordinate des Drehachsen-Vektors.

Beispiele

x-Komponente einer 3D-Drehung auslesen

// Drehung um 45° um die Achse (1, 0, 0), also um die x-Achse
const rot = new CSSRotate(1, 0, 0, CSS.deg(45));

console.log(rot.x.value); // reiner Zahlenwert
console.log(rot.x.unit);  // einheitenlos
console.log(rot.is2D);
console.log(rot.toString());

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

Standardwerte bei einer 2D-Drehung

// Nur Winkel angegeben: Drehung in der Ebene um die z-Achse
const rot2d = new CSSRotate(CSS.deg(30));

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

0 0 1 true rotate(30deg)

Drehachse eines Elements per Skript ändern

// HTML: <div id="box" style="transform: rotate3d(0, 1, 0, 60deg)"></div>
const box = document.querySelector('#box');

const transform = box.attributeStyleMap.get('transform'); // CSSTransformValue
const rot = transform[0];                                   // CSSRotate

rot.x = 1;              // Zahl ist erlaubt
rot.y = CSS.number(1);  // CSSNumericValue ebenfalls

box.attributeStyleMap.set('transform', transform);
console.log(box.style.transform);

rotate3d(1, 1, 0, 60deg)

Ungültige Zuweisung abfangen

const rot = new CSSRotate(1, 0, 0, CSS.deg(90));

try {
  rot.x = CSS.px(2); // Einheit nicht erlaubt
} catch (err) {
  console.log(err.name);
}
console.log(rot.x.value); // bleibt unverändert

TypeError 1

// Wichtig · Fallstricke

Browser-Unterstützung: Das CSS Typed OM gibt es in Chromium-Browsern (Chrome und Edge ab 79) und in Safari ab 16.4. Firefox unterstützt es nicht. Prüfe die Unterstützung vorher, z. B. mit 'CSSRotate' in window, und sieh bei Bedarf einen Rückweg über element.style.transform vor.
Kein Einheitenwert: x muss einheitenlos sein. Werte wie CSS.px() oder CSS.deg() lösen einen TypeError aus.
Rückgabe ist ein Objekt: rot.x liefert keinen primitiven Wert, sondern ein CSSNumericValue. Für Vergleiche und Berechnungen verwendest du rot.x.value.
Nullvektor: Sind x, y und z alle 0, gibt es keine gültige Drehachse. Der Browser führt dann keine Drehung aus.
Änderung wirkt nicht automatisch: Wenn du x an einem ausgelesenen Objekt änderst, ändert sich der Stil des Elements nicht. Du musst den CSSTransformValue mit attributeStyleMap.set() zurückschreiben.
Aus computedStyleMap() bekommst du für transform oft eine CSSMatrixComponent statt eines CSSRotate. Die einzelnen Drehwerte liest du daher besser aus attributeStyleMap.

Siehe auch

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