new CSSRotate() — Methode · JavaScript-Referenz

Signatur

new CSSRotate(angle) | new CSSRotate(x, y, z, angle)

Beschreibung

Der Konstruktor CSSRotate() gehört zum CSS Typed Object Model (CSS Typed OM). Er erzeugt ein Objekt, das eine Drehung als typisierten Wert abbildet und nicht als Zeichenkette. Solche Objekte werden meist in ein CSSTransformValue gepackt und über element.attributeStyleMap oder CSSStyleRule.styleMap gesetzt.

Es gibt zwei Aufrufformen:

new CSSRotate(angle) – eine 2D-Drehung, entspricht rotate(angle). Die Eigenschaft is2D ist dabei true, und die Achse ist (0, 0, 1).
new CSSRotate(x, y, z, angle) – eine 3D-Drehung um den Vektor (x, y, z), entspricht rotate3d(x, y, z, angle). Hier ist is2D gleich false.

Der Vorteil gegenüber Zeichenketten wie `rotate(${deg}deg)`: Die Werte lassen sich direkt lesen und ändern (rotation.angle.value += 5). Der Browser muss dabei keine Zeichenketten zerlegen, und Einheitenfehler fallen schon beim Erzeugen auf, weil dann ein TypeError geworfen wird. Das ist vor allem bei Animationen in Schleifen praktisch.

Parameter

Name	Typ	Beschreibung
$angle Pflicht	CSSNumericValue	Drehwinkel. Muss eine Winkeleinheit haben, z. B. `CSS.deg(45)`, `CSS.rad(1)`, `CSS.turn(0.25)` oder `CSS.grad(50)`. In der 4-Argument-Form ist er der vierte Parameter.
$x	number \| CSSNumericValue	X-Anteil der Drehachse (nur 3D-Form). Muss einheitenlos sein, also eine Zahl oder `CSS.number()`.
$y	number \| CSSNumericValue	Y-Anteil der Drehachse (nur 3D-Form), einheitenlos.
$z	number \| CSSNumericValue	Z-Anteil der Drehachse (nur 3D-Form), einheitenlos.

Rückgabewert

Typ

CSSRotate

Beschreibung

Ein neues CSSRotate-Objekt mit den Eigenschaften x, y, z, angle und is2D. Die Methoden toString() und toMatrix() erbt es von CSSTransformComponent.

Beispiele

2D-Drehung erzeugen und auslesen

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

console.log(rotation.toString());
console.log(rotation.is2D);
console.log(rotation.angle.value, rotation.angle.unit);

rotate(45deg) true 45 "deg"

3D-Drehung um eine eigene Achse

const rotation3d = new CSSRotate(1, 1, 0, CSS.turn(0.5));

console.log(rotation3d.toString());
console.log(rotation3d.is2D);

// Matrix für eigene Berechnungen
const matrix = rotation3d.toMatrix();
console.log(matrix instanceof DOMMatrix);

rotate3d(1, 1, 0, 0.5turn) false true

Element per attributeStyleMap drehen und animieren

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

if ('CSSRotate' in window && box.attributeStyleMap) {
  const rotation = new CSSRotate(CSS.deg(0));
  const transform = new CSSTransformValue([rotation]);

  const tick = () => {
    // Winkel direkt ändern, ohne Zeichenketten zu zerlegen
    rotation.angle.value = (rotation.angle.value + 2) % 360;
    box.attributeStyleMap.set('transform', transform);
    requestAnimationFrame(tick);
  };
  requestAnimationFrame(tick);
} else {
  // Rückfall für Browser ohne CSS Typed OM (z. B. Firefox)
  box.style.transform = 'rotate(0deg)';
}

Ungültige Einheit führt zu TypeError

try {
  new CSSRotate(CSS.px(10)); // Länge statt Winkel
} catch (err) {
  console.log(err.name);
}

try {
  new CSSRotate(CSS.px(1), 0, 0, CSS.deg(30)); // Achse mit Einheit
} catch (err) {
  console.log(err.name);
}

TypeError TypeError

// Wichtig · Fallstricke

Browser-Kompatibilität: CSS Typed OM gibt es in Chromium-Browsern (Chrome, Edge, Opera) ab Version 66 und in Safari ab 16.4. Firefox unterstützt es nicht. Vor der Nutzung mit 'CSSRotate' in window prüfen und eine Zeichenkette über element.style.transform als Rückfall vorsehen.
Nicht die Einzeleigenschaft rotate: CSSRotate steht für die Funktion rotate() innerhalb von transform. Für die eigenständige CSS-Eigenschaft rotate ist es nicht gedacht.
Einheiten werden geprüft: angle muss eine Winkeleinheit haben. x, y und z müssen einheitenlos sein. Sonst wird ein TypeError geworfen. Eine reine Zahl als Winkel, etwa new CSSRotate(45), ist ebenfalls ungültig; stattdessen CSS.deg(45) verwenden.
Nur 1 oder 4 Argumente: Bei 2 oder 3 Argumenten wird der Aufruf nicht als 3D-Drehung gelesen, sondern schlägt fehl.
is2D umschalten: Wird is2D nachträglich auf true gesetzt, ignoriert die Ausgabe (toString(), toMatrix()) die Achse x/y/z.
Ein CSSRotate allein kann nicht an attributeStyleMap.set() übergeben werden. Es muss in einem CSSTransformValue stecken.

Siehe auch

new CSSScale() new CSSTranslate() new AudioData() new CSSMathMax() new CSSMathMin()