DOMMatrix.translateSelf() — Methode · JavaScript-Referenz

Signatur

DOMMatrix.prototype.translateSelf(translateX, translateY, translateZ)

Beschreibung

translateSelf() ist die verändernde Variante von DOMMatrixReadOnly.translate(). Die Methode multipliziert die aktuelle Matrix von rechts mit einer Verschiebungsmatrix (this = this × T) und schreibt das Ergebnis in das bestehende Objekt zurück. Es wird also kein neues Objekt erzeugt.

Weil die Verschiebung von rechts multipliziert wird, wirkt sie im lokalen Koordinatensystem der bisherigen Transformation. Wurde die Matrix vorher skaliert oder gedreht, wird die Verschiebung ebenfalls skaliert bzw. gedreht. Das Verhalten entspricht der CSS-Schreibweise transform: scale(2) translate(10px, 5px).

Die Methode gibt die Matrix selbst zurück. Dadurch lassen sich mehrere …Self()-Aufrufe verketten. Praktisch ist das etwa bei Drag-and-Drop, bei Kamera- und Viewport-Logik in Canvas-Anwendungen oder überall dort, wo eine Transformation in Schleifen immer wieder angepasst wird und man keine neuen Objekte erzeugen möchte.

Wenn translateZ ungleich 0 ist, wird die Matrix zu einer 3D-Matrix: is2D wird dann false, und toString() gibt matrix3d(…) aus.

Parameter

Name	Typ	Beschreibung
$translateX	number	Verschiebung entlang der x-Achse.
$translateY	number	Verschiebung entlang der y-Achse.
$translateZ	number	Verschiebung entlang der z-Achse. Ein Wert ungleich `0` macht die Matrix zu einer 3D-Matrix (`is2D === false`).

Rückgabewert

Typ

DOMMatrix

Beschreibung

Dieselbe DOMMatrix-Instanz, jetzt verändert. Kein neues Objekt.

Beispiele

Einfache 2D-Verschiebung

const m = new DOMMatrix();
const result = m.translateSelf(10, 20);

console.log(m.toString());
console.log(result === m); // dasselbe Objekt
console.log(m.e, m.f);

matrix(1, 0, 0, 1, 10, 20) true 10 20

Verkettung: Reihenfolge ist wichtig

// Erst skalieren, dann verschieben: Die Verschiebung wird mitskaliert
const a = new DOMMatrix().scaleSelf(2).translateSelf(10, 5);
console.log(a.toString());

// Erst verschieben, dann skalieren
const b = new DOMMatrix().translateSelf(10, 5).scaleSelf(2);
console.log(b.toString());

matrix(2, 0, 0, 2, 20, 10) matrix(2, 0, 0, 2, 10, 5)

Element beim Ziehen verschieben

const box = document.querySelector('#box');
const matrix = new DOMMatrix();
let last = null;

box.addEventListener('pointerdown', (e) => {
  last = { x: e.clientX, y: e.clientY };
  box.setPointerCapture(e.pointerId);
});

box.addEventListener('pointermove', (e) => {
  if (!last) return;
  // Matrix direkt verändern, ohne neues Objekt zu erzeugen
  matrix.translateSelf(e.clientX - last.x, e.clientY - last.y);
  last = { x: e.clientX, y: e.clientY };
  box.style.transform = matrix.toString();
});

box.addEventListener('pointerup', () => { last = null; });

3D-Verschiebung und Einsatz im Canvas

const m3d = new DOMMatrix().translateSelf(0, 0, 50);
console.log(m3d.is2D);
console.log(m3d.toString());

// 2D-Kamera für Canvas
const ctx = document.querySelector('canvas').getContext('2d');
const camera = new DOMMatrix().translateSelf(100, 50);
ctx.setTransform(camera);
ctx.fillRect(0, 0, 20, 20); // wird bei (100, 50) gezeichnet

false matrix3d(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 50, 1)

// Wichtig · Fallstricke

Verändert das Objekt: Wird dieselbe Matrix an mehreren Stellen verwendet, wirkt sich die Änderung überall aus. Wer das Original behalten will, nimmt matrix.translate(), das eine neue Matrix zurückgibt.
Nur bei DOMMatrix: DOMMatrixReadOnly hat keine Methode translateSelf(). Ein Aufruf dort löst einen TypeError aus.
Die Reihenfolge zählt: Die Verschiebung wird von rechts multipliziert und wirkt deshalb im bereits transformierten Koordinatensystem. Soll in globalen Koordinaten verschoben werden, verwendet man new DOMMatrix().translateSelf(x, y).multiplySelf(m) oder m.preMultiplySelf(new DOMMatrix().translateSelf(x, y)).
Ist translateZ ungleich 0, wird is2D dauerhaft false. Das bleibt auch dann so, wenn man später wieder zurückverschiebt.
Werte wie NaN werden nicht geprüft und machen die Matrix unbrauchbar.
Kompatibilität: In allen modernen Browsern und in Web-Workern verfügbar. Node.js hat DOMMatrix nicht fest eingebaut; dort braucht man Polyfills oder Pakete wie canvas oder dommatrix.

Siehe auch

DOMMatrix DOMMatrixReadOnly.translate() DOMMatrix.scaleSelf() DOMMatrix.rotateSelf() DOMMatrix.multiplySelf() DOMMatrix.preMultiplySelf() CanvasRenderingContext2D.setTransform()