DOMMatrixReadOnly.scale3d() — Methode · JavaScript-Referenz

Signatur

DOMMatrixReadOnly.prototype.scale3d(scale, originX, originY, originZ)

Beschreibung

scale3d() multipliziert die aktuelle Matrix mit einer gleichmäßigen 3D-Skalierung: x, y und z werden mit demselben Faktor scale gestreckt oder gestaucht. Die Ausgangsmatrix bleibt dabei unverändert. Sie erhalten immer eine neue DOMMatrix, auch wenn Sie die Methode auf einer DOMMatrixReadOnly aufrufen.

Mit den optionalen Parametern originX, originY und originZ legen Sie den Fixpunkt der Skalierung fest. Intern entspricht das der Folge translate(originX, originY, originZ) → scale3d(scale) → translate(-originX, -originY, -originZ). So funktioniert es auch bei transform-origin in CSS.

Typische Einsatzgebiete sind das Berechnen von CSS-Transformationen in JavaScript, zum Beispiel für Zoom-Effekte in 3D-Szenen, das Umrechnen von Punkten mit transformPoint() und das Verketten mehrerer Transformationen, ohne Matrixwerte selbst auszurechnen. Wenn Sie die Achsen unterschiedlich skalieren wollen, nehmen Sie stattdessen scale(). Diese Methode akzeptiert eigene Faktoren für x, y und z.

Parameter

Name	Typ	Default	Beschreibung
$scale	number	1	Skalierungsfaktor, der gleichzeitig auf die x-, y- und z-Achse wirkt. Werte zwischen 0 und 1 verkleinern, Werte über 1 vergrößern, negative Werte spiegeln zusätzlich.
$originX	number	0	x-Koordinate des Ursprungspunkts, um den skaliert wird.
$originY	number	0	y-Koordinate des Ursprungspunkts, um den skaliert wird.
$originZ	number	0	z-Koordinate des Ursprungspunkts, um den skaliert wird.

Rückgabewert

Typ

DOMMatrix

Beschreibung

Eine neue DOMMatrix, das Produkt aus der Ausgangsmatrix und der 3D-Skalierung. Die Ausgangsmatrix wird nicht verändert.

Beispiele

Gleichmäßig auf allen Achsen verdoppeln

const identitaet = new DOMMatrixReadOnly();
const skaliert = identitaet.scale3d(2);

console.log(skaliert.toString());
console.log(skaliert.is2D);
// Die Ausgangsmatrix bleibt unverändert
console.log(identitaet.toString());

matrix3d(2, 0, 0, 0, 0, 2, 0, 0, 0, 0, 2, 0, 0, 0, 0, 1) false matrix(1, 0, 0, 1, 0, 0)

Skalieren um einen Ursprungspunkt (wie transform-origin)

// Um den Mittelpunkt eines 100×100-Elements skalieren
const m = new DOMMatrixReadOnly().scale3d(2, 50, 50, 0);
console.log(m.toString());

// Der Mittelpunkt bleibt fix, die Ecke wandert nach außen
const mitte = m.transformPoint(new DOMPoint(50, 50, 0));
const ecke = m.transformPoint(new DOMPoint(0, 0, 0));
console.log(mitte.x, mitte.y, mitte.z);
console.log(ecke.x, ecke.y, ecke.z);

matrix3d(2, 0, 0, 0, 0, 2, 0, 0, 0, 0, 2, 0, -50, -50, 0, 1) 50 50 0 -50 -50 0

Transformation verketten und auf ein Element anwenden

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

const transform = new DOMMatrixReadOnly()
  .translate(0, 0, -100)
  .rotate(0, 30, 0)
  .scale3d(1.2); // zum Schluss gleichmäßig vergrößern

// toString() liefert eine gültige CSS-Funktion matrix3d(...)
karte.style.transform = transform.toString();

// Wichtig · Fallstricke

Nicht verändernd: scale3d() gibt immer eine neue Matrix zurück. Um eine bestehende DOMMatrix direkt zu ändern, verwenden Sie DOMMatrix.prototype.scale3dSelf().
Nur ein Faktor: Alle drei Achsen werden gleich skaliert. Für unterschiedliche Faktoren nehmen Sie scale(scaleX, scaleY, scaleZ, originX, originY, originZ).
2D-Status geht verloren: Ein Faktor ungleich 1 verändert m33. Die Ergebnis-Matrix hat dann is2D === false, und toString() liefert matrix3d(...) statt matrix(...).
Reihenfolge zählt: Die Skalierung wird von rechts an die bestehende Matrix multipliziert. m.translate(...).scale3d(2) ergibt deshalb etwas anderes als m.scale3d(2).translate(...).
Bei einem Faktor von 0 ist die Matrix nicht mehr invertierbar. inverse() liefert dann eine Matrix aus lauter NaN. Nicht endliche Werte führen außerdem dazu, dass toString() einen Fehler wirft.
Kompatibilität: Wird in allen aktuellen Browsern und in Web Workern unterstützt. Ältere WebKit-Versionen kennen nur WebKitCSSMatrix, heute ein Alias für DOMMatrix. In Node.js ist DOMMatrix nicht eingebaut.

Siehe auch

DOMMatrixReadOnly DOMMatrixReadOnly.scale() DOMMatrix.scale3dSelf() DOMMatrixReadOnly.translate() DOMMatrixReadOnly.transformPoint() DOMMatrixReadOnly.is2D new XRLayerEvent()