DOMMatrixReadOnly.scale() — Methode · JavaScript-Referenz

Signatur

DOMMatrixReadOnly.prototype.scale(scaleX, scaleY, scaleZ, originX, originY, originZ)

Beschreibung

Die Methode scale() von DOMMatrixReadOnly multipliziert die aktuelle Matrix von rechts mit einer Skalierungsmatrix und gibt das Ergebnis als neue DOMMatrix zurück. Die Ausgangsmatrix bleibt unverändert. Das entspricht einer CSS-Transformation, bei der scale(…) an die vorhandenen Transformationen angehängt wird.

Man kann jede Achse einzeln skalieren (scaleX, scaleY, scaleZ) und einen Ursprungspunkt angeben, um den skaliert wird (originX, originY, originZ). Intern entspricht das: erst zum Ursprung verschieben, skalieren, wieder zurückverschieben – so wie transform-origin in CSS.

Typische Einsatzfälle sind Zoom-Funktionen in Canvas- oder SVG-Anwendungen, das Umrechnen von Koordinaten zwischen Koordinatensystemen und das programmatische Erzeugen von CSS-transform-Werten. Wenn die Matrix direkt verändert werden soll, nimmt man stattdessen DOMMatrix.prototype.scaleSelf().

Parameter

Name	Typ	Default	Beschreibung
$scaleX	number	1	Skalierungsfaktor entlang der x-Achse.
$scaleY	number	scaleX	Skalierungsfaktor entlang der y-Achse. Fehlt der Wert, wird `scaleX` übernommen (gleichmäßige Skalierung).
$scaleZ	number	1	Skalierungsfaktor entlang der z-Achse. Ein Wert ungleich `1` macht das Ergebnis zu einer 3D-Matrix.
$originX	number	0	x-Koordinate des Ursprungs, um den skaliert wird.
$originY	number	0	y-Koordinate des Ursprungs, um den skaliert wird.
$originZ	number	0	z-Koordinate des Ursprungs. Ein Wert ungleich `0` macht das Ergebnis zu einer 3D-Matrix.

Rückgabewert

Typ

DOMMatrix

Beschreibung

Eine neue DOMMatrix mit der angewendeten Skalierung. Die Originalmatrix wird nicht verändert.

Beispiele

Gleichmäßige und ungleichmäßige Skalierung

const basis = new DOMMatrixReadOnly();

const doppelt = basis.scale(2);         // scaleY übernimmt scaleX
const verzerrt = basis.scale(3, 0.5);

console.log(doppelt.toString());
console.log(verzerrt.toString());
console.log(basis.toString()); // Original bleibt unverändert

matrix(2, 0, 0, 2, 0, 0) matrix(3, 0, 0, 0.5, 0, 0) matrix(1, 0, 0, 1, 0, 0)

Um einen Ursprungspunkt zoomen

// Um den Mittelpunkt (50, 50) einer 100×100-Fläche verdoppeln
const zoom = new DOMMatrixReadOnly().scale(2, 2, 1, 50, 50);
console.log(zoom.toString());

// Der Mittelpunkt bleibt an seiner Position
const mitte = new DOMPoint(50, 50).matrixTransform(zoom);
console.log(mitte.x, mitte.y);

const ecke = new DOMPoint(0, 0).matrixTransform(zoom);
console.log(ecke.x, ecke.y);

matrix(2, 0, 0, 2, -50, -50) 50 50 -50 -50

Zoom per Mausrad auf ein Element anwenden

const box = document.querySelector('#bild');
let matrix = new DOMMatrixReadOnly();

box.addEventListener('wheel', (event) => {
  event.preventDefault();
  const faktor = event.deltaY < 0 ? 1.1 : 1 / 1.1;
  // Um die Mausposition relativ zum Element zoomen
  const { left, top } = box.getBoundingClientRect();
  const punkt = new DOMPoint(event.clientX - left, event.clientY - top)
    .matrixTransform(matrix.inverse());
  matrix = matrix.scale(faktor, faktor, 1, punkt.x, punkt.y);
  box.style.transformOrigin = '0 0';
  box.style.transform = matrix.toString();
}, { passive: false });

3D-Skalierung erzeugt 3D-Matrix

const m2d = new DOMMatrixReadOnly().scale(2);
const m3d = new DOMMatrixReadOnly().scale(2, 2, 2);

console.log(m2d.is2D);
console.log(m3d.is2D);
console.log(m3d.m33);

true false 2

// Wichtig · Fallstricke

Keine Mutation: scale() liefert immer eine neue Matrix. Wer das Ergebnis nicht zuweist (m.scale(2);), verliert es. Für Änderungen direkt an der Matrix gibt es DOMMatrix.prototype.scaleSelf().
Reihenfolge zählt: Die Skalierung wird nach rechts multipliziert, also im lokalen Koordinatensystem angewendet. m.translate(10, 0).scale(2) und m.scale(2).translate(10, 0) führen zu unterschiedlichen Ergebnissen.
2D/3D: Ist scaleZ ungleich 1 oder originZ ungleich 0, wird das Ergebnis zur 3D-Matrix (is2D === false) und toString() liefert dann matrix3d(…).
Ältere Signatur: Frühe Entwürfe der Geometry-Spezifikation und ältere Browserversionen kannten scale(scale, originX, originY). In sehr alten Browsern kann die Bedeutung des zweiten und dritten Arguments daher abweichen. Das veraltete scaleNonUniform() sollte nicht mehr verwendet werden.
Ein Faktor von 0 ergibt eine nicht invertierbare Matrix; inverse() liefert dann eine Matrix aus NaN-Werten.
Verfügbar in allen modernen Browsern und in Web Workern, in Node.js aber nicht nativ.

Siehe auch

DOMMatrixReadOnly DOMMatrix.scaleSelf() DOMMatrixReadOnly.scale3d() DOMMatrixReadOnly.translate() DOMMatrixReadOnly.rotate() DOMMatrixReadOnly.multiply()