DOMMatrixReadOnly.rotate() — Methode · JavaScript-Referenz

Signatur

DOMMatrixReadOnly.prototype.rotate(rotX, rotY, rotZ)

Beschreibung

rotate() dreht eine Transformationsmatrix und gibt das Ergebnis als neue DOMMatrix zurück. Die Ausgangsmatrix bleibt dabei unverändert. Die Methode eignet sich für Canvas-Zeichnungen, eigene Animationen, Kollisionsberechnungen oder dafür, CSS-Transformationen in JavaScript nachzubauen, ohne selbst mit Sinus und Kosinus zu rechnen.

Die Winkel werden in Grad angegeben, nicht im Bogenmaß. Wie die Argumente ausgewertet werden, hängt davon ab, wie viele du übergibst:

Nur ein Argument (rotate(30)): Der Wert gilt als Drehung um die Z-Achse. Das ist die übliche 2D-Drehung und entspricht rotate(30deg) in CSS.
Zwei oder drei Argumente: Sie werden als rotX, rotY und rotZ gelesen. Fehlende Werte gelten als 0.

Intern wird die aktuelle Matrix von rechts mit Drehmatrizen multipliziert: zuerst um die Z-Achse (rotZ), dann um die Y-Achse (rotY), dann um die X-Achse (rotX). Sobald rotX oder rotY ungleich 0 ist, wird die Ergebnismatrix zu einer 3D-Matrix (is2D === false). toString() liefert dann matrix3d(...) statt matrix(...).

Gedreht wird immer um den Ursprung (0, 0) des aktuellen Koordinatensystems. Soll um einen anderen Punkt gedreht werden, z. B. die Mitte eines Objekts, verschiebst du vorher mit translate() dorthin und danach wieder zurück.

Parameter

Name	Typ	Beschreibung
$rotX	number	Drehwinkel in Grad um die X-Achse. Achtung: Wird nur dieser Parameter übergeben, gilt er als Drehung um die Z-Achse (2D-Drehung).
$rotY	number	Drehwinkel in Grad um die Y-Achse. Ein Wert ungleich `0` macht die Matrix zur 3D-Matrix.
$rotZ	number	Drehwinkel in Grad um die Z-Achse (Drehung in der Bildebene).

Rückgabewert

Typ

DOMMatrix

Beschreibung

Eine neue, veränderbare DOMMatrix mit dem Ergebnis der Drehung. Die Quellmatrix bleibt unverändert.

Beispiele

Einfache 2D-Drehung um 30 Grad

const m = new DOMMatrixReadOnly();
const rotated = m.rotate(30); // ein Argument = Drehung um die Z-Achse

console.log(rotated.a.toFixed(4), rotated.b.toFixed(4));
console.log(rotated.is2D);
console.log(m.isIdentity); // Original bleibt unverändert

0.8660 0.5000 true true

Punkt um 90 Grad drehen (mit Rundung)

const matrix = new DOMMatrix().rotate(90);
const p = new DOMPoint(10, 0).matrixTransform(matrix);

// Gleitkomma-Ungenauigkeit: x ist nicht exakt 0
console.log(p.x);
console.log(Math.round(p.x), Math.round(p.y));

6.123233995736766e-16 0 10

Canvas: Rechteck um den eigenen Mittelpunkt drehen

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');

const drawRotatedRect = (x, y, w, h, angle) => {
  const cx = x + w / 2;
  const cy = y + h / 2;
  // Zum Mittelpunkt verschieben, drehen, zurückverschieben
  const transform = new DOMMatrix()
    .translate(cx, cy)
    .rotate(angle)
    .translate(-cx, -cy);

  ctx.setTransform(transform);
  ctx.fillStyle = 'tomato';
  ctx.fillRect(x, y, w, h);
  ctx.resetTransform();
};

let angle = 0;
const loop = () => {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  drawRotatedRect(100, 100, 80, 40, angle);
  angle = (angle + 2) % 360;
  requestAnimationFrame(loop);
};
loop();

3D-Drehung und Übertragung auf ein Element

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

// 20° um X, 45° um Y, keine Z-Drehung
const m = new DOMMatrix().rotate(20, 45, 0);

console.log(m.is2D);
console.log(m.toString().startsWith('matrix3d('));

card.style.transform = m.toString();

false true

// Wichtig · Fallstricke

Grad statt Bogenmaß: Anders als Math.sin() oder CanvasRenderingContext2D.rotate() erwartet rotate() Grad. Werte in Bogenmaß rechnest du mit rad * 180 / Math.PI um.
Ein Argument vs. mehrere: rotate(45) dreht um die Z-Achse, rotate(45, 0) dagegen um die X-Achse. Dieser Unterschied führt leicht zu Fehlern.
Reihenfolge: Es wird zuerst um Z, dann um Y, dann um X gedreht. Für Drehungen um eine beliebige Achse ist rotateAxisAngle() klarer.
Unveränderlich: Die Methode ändert die Matrix nicht selbst. Wer eine vorhandene DOMMatrix direkt ändern will, nimmt DOMMatrix.prototype.rotateSelf().
Gleitkomma: Bei 90°, 180° usw. entstehen winzige Restwerte wie 6e-17 statt 0. Vor Vergleichen oder einer Anzeige solltest du runden.
Kompatibilität: Wird in allen aktuellen Browsern unterstützt, auch in Web Workern. Ältere WebKit-Versionen kennen nur WebKitCSSMatrix. In Node.js gibt es DOMMatrix nicht von Haus aus.

Siehe auch

DOMMatrixReadOnly.scale() DOMMatrixReadOnly.toJSON() DOMMatrixReadOnly.translate() DOMMatrixReadOnly.flipX() DOMMatrixReadOnly.flipY() new RTCIceCandidate() new VideoColorSpace()