CSSRotate — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSRotate extends CSSTransformComponent

Beschreibung

CSSRotate gehört zur CSS Typed Object Model API (Houdini). Ein Objekt dieses Typs steht für eine einzelne Rotationsfunktion innerhalb einer transform-Eigenschaft, also rotate(45deg) oder rotate3d(1, 0, 0, 90deg). Mehrere solcher Bausteine werden in einem CSSTransformValue gesammelt. Diesen Wert setzt oder liest man dann über element.attributeStyleMap bzw. element.computedStyleMap().

Der Konstruktor hat zwei Formen: new CSSRotate(angle) erzeugt eine 2D-Drehung um die Z-Achse (x = 0, y = 0, z = 1, is2D = true). new CSSRotate(x, y, z, angle) erzeugt eine 3D-Drehung um den Vektor (x, y, z). Die Eigenschaften x, y, z (Zahlen bzw. CSSNumericValue vom Typ Zahl) und angle (CSSNumericValue vom Typ Winkel) lassen sich nachträglich lesen und ändern.

Von CSSTransformComponent erbt CSSRotate die Eigenschaft is2D sowie die Methoden toMatrix() (liefert eine DOMMatrix) und toString() (liefert die CSS-Schreibweise). Der Vorteil gegenüber dem Zusammenbauen von Strings: Man muss keine Strings parsen, es entstehen weniger Fehler, und man kann gezielt z. B. nur den Winkel einer bestehenden Transformation ändern. Das ist bei Animationen per JavaScript nützlich.

Parameter

Name	Typ	Default	Beschreibung
$x	number \| CSSNumericValue	0	X-Komponente des Drehachsen-Vektors. Nur bei der 4-Argument-Form; muss eine einheitenlose Zahl sein.
$y	number \| CSSNumericValue	0	Y-Komponente des Drehachsen-Vektors. Nur bei der 4-Argument-Form.
$z	number \| CSSNumericValue	1	Z-Komponente des Drehachsen-Vektors. Nur bei der 4-Argument-Form.
$angle Pflicht	CSSNumericValue		Drehwinkel, z. B. `CSS.deg(45)`, `CSS.rad(1)` oder `CSS.turn(0.25)`. Muss vom Typ Winkel sein, sonst wird ein `TypeError` ausgelöst.

Rückgabewert

Typ

CSSRotate

Beschreibung

Ein neues CSSRotate-Objekt mit den Eigenschaften x, y, z, angle und is2D.

Beispiele

2D- und 3D-Rotation erzeugen

// 2D: Drehung um die Z-Achse
const rot2d = new CSSRotate(CSS.deg(45));
console.log(rot2d.toString(), rot2d.is2D);

// 3D: Drehung um die X-Achse
const rot3d = new CSSRotate(1, 0, 0, CSS.deg(90));
console.log(rot3d.toString(), rot3d.is2D);

rotate(45deg) true rotate3d(1, 0, 0, 90deg) false

Rotation per attributeStyleMap auf ein Element anwenden

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

const transform = new CSSTransformValue([
  new CSSTranslate(CSS.px(20), CSS.px(0)),
  new CSSRotate(CSS.turn(0.25))
]);

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

translate(20px, 0px) rotate(0.25turn)

Winkel einer bestehenden Transformation auslesen und animieren

const el = document.querySelector('.spinner');
el.style.transform = 'rotate(30deg) scale(1.2)';

const value = el.attributeStyleMap.get('transform');
const rotation = [...value].find((c) => c instanceof CSSRotate);
console.log(rotation.angle.value, rotation.angle.unit);

// Nur den Winkel hochzählen, ohne Strings zu parsen
const tick = () => {
  rotation.angle = CSS.deg((rotation.angle.value + 2) % 360);
  el.attributeStyleMap.set('transform', value);
  requestAnimationFrame(tick);
};
requestAnimationFrame(tick);

30 "deg"

In eine DOMMatrix umwandeln

const rot = new CSSRotate(CSS.deg(90));
const m = rot.toMatrix();
console.log(m.is2D, Math.round(m.a), Math.round(m.b));

true 0 1

// Wichtig · Fallstricke

Browser-Unterstützung: Das CSS Typed OM gibt es in Chromium-Browsern (ab 66) und in Safari (ab 16.4). Firefox unterstützt es nicht. Prüfen Sie die Verfügbarkeit mit if ('CSSRotate' in window) und greifen Sie sonst auf element.style.transform mit Strings zurück.
angle muss ein Winkel-Wert sein (deg, rad, grad, turn). Eine einfache Zahl oder CSS.px() löst einen TypeError aus. Umgekehrt müssen x, y und z einheitenlos sein.
Eine Änderung am CSSRotate-Objekt wirkt sich nicht automatisch auf das Element aus. Den geänderten CSSTransformValue müssen Sie erneut mit attributeStyleMap.set() zuweisen.
Wenn Sie is2D manuell auf true setzen, gibt toString() nur rotate(angle) aus. Die Achsenwerte fallen dann weg.
Die berechnete Transformation (computedStyleMap()) kann je nach Browser anders aussehen als die angegebenen Funktionen. Wenn Sie gezielt nach CSSRotate-Bausteinen suchen, lesen Sie lieber attributeStyleMap.
Nicht verwechseln mit der eigenständigen CSS-Eigenschaft rotate. CSSRotate bildet nur Funktionen innerhalb von transform ab.

Siehe auch

CSSRule CSSScale CSSTranslate CSSValue Storage