Signatur
Beschreibung
translate() berechnet eine neue Transformationsmatrix, bei der eine Verschiebung (Translation) an die bestehende Matrix angehängt wird. Die ursprüngliche Matrix bleibt unverändert. Das Ergebnis ist immer eine veränderbare DOMMatrix, auch wenn die Methode auf einer DOMMatrixReadOnly aufgerufen wird.
Mathematisch wird die Matrix von rechts mit einer Translationsmatrix multipliziert (this × T(tx, ty, tz)). Die Verschiebung findet also im lokalen Koordinatensystem der bisherigen Transformation statt: Wurde die Matrix vorher z. B. um 90° gedreht, verschiebt translate(10, 0) entlang der gedrehten x-Achse. Das entspricht dem Verhalten der CSS-Eigenschaft transform, bei der Funktionen von links nach rechts verkettet werden.
Typische Einsatzgebiete sind das Zusammensetzen von Transformationen für element.style.transform, Berechnungen für Canvas-Zeichnungen (CanvasRenderingContext2D.setTransform()), Hit-Testing mit transformPoint() sowie Pan-/Zoom-Logik in Editoren und Karten.
Wird ein tz ungleich 0 übergeben, wird die Ergebnis-Matrix zu einer 3D-Matrix (is2D === false) und wird von toString() als matrix3d(...) ausgegeben.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $tx | number | 0 | Verschiebung entlang der x-Achse (in CSS-Pixeln, wenn die Matrix für CSS genutzt wird). |
| $ty | number | 0 | Verschiebung entlang der y-Achse. |
| $tz | number | 0 | Verschiebung entlang der z-Achse. Ein Wert ungleich 0 macht die Ergebnis-Matrix zu einer 3D-Matrix. |
Rückgabewert
DOMMatrix, die der ursprünglichen Matrix mit angehängter Translation entspricht. Die Ausgangsmatrix wird nicht verändert.Beispiele
Einfache 2D-Verschiebung
const base = new DOMMatrixReadOnly();
const moved = base.translate(10, 20);
console.log(moved.e, moved.f);
console.log(moved.toString());
console.log(base.toString()); // Original bleibt unverändert
console.log(moved instanceof DOMMatrix);Reihenfolge beachten: Skalieren, dann Verschieben
const m1 = new DOMMatrix().scale(2).translate(10, 0);
const m2 = new DOMMatrix().translate(10, 0).scale(2);
// Bei m1 wird im skalierten Koordinatensystem verschoben
console.log(m1.e); // 10 * 2
console.log(m2.e);3D-Translation und Anwendung auf ein Element
const card = document.querySelector('.card');
const matrix = new DOMMatrix()
.translate(100, 50, 30)
.rotate(0, 20, 0);
console.log(matrix.is2D);
card.style.transform = matrix.toString();Punkt verschieben (z. B. für Pan-Logik)
const view = new DOMMatrixReadOnly().scale(1.5);
const panned = view.translate(-40, 25);
const p = panned.transformPoint(new DOMPoint(100, 100));
console.log(p.x, p.y);// Wichtig · Fallstricke
- Unveränderlich vs. veränderlich:
translate()erzeugt bei jedem Aufruf eine neue Matrix. Wenn du eine vorhandeneDOMMatrixdirekt ändern willst (z. B. in einer Animationsschleife, um Speicherzuweisungen zu vermeiden), nutzeDOMMatrix.prototype.translateSelf(). - Reihenfolge: Die Translation wird von rechts multipliziert und wirkt daher im bereits transformierten Koordinatensystem.
rotate(90).translate(10, 0)verschiebt nach unten, nicht nach rechts. - Gleitkomma-Ungenauigkeit: Nach Rotationen entstehen Werte wie
6.123e-17statt0. Vergleiche daher mit einer Toleranz, nicht mit===. - 2D/3D: Schon
tzungleich0setztis2Ddauerhaft auffalse. Auch eine spätere Rückverschiebung um-tzmacht die Matrix nicht wieder zu einer 2D-Matrix. - Kompatibilität: In allen modernen Browsern und in Web Workern verfügbar. In Node.js gibt es
DOMMatrixnicht von Haus aus; dort brauchst du ein Polyfill oder eine Bibliothek (z. B. übercanvas-Pakete). Das ältereWebKitCSSMatrixist in vielen Browsern ein Alias vonDOMMatrix.