CanvasRenderingContext2D.translate() — Methode · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.prototype.translate(x, y)

Beschreibung

translate() verschiebt den Ursprungspunkt (0, 0) des Zeichenkontexts. Alle danach gezeichneten Formen, Pfade, Texte und Bilder werden relativ zum neuen Ursprung positioniert. Bereits Gezeichnetes bleibt unverändert, denn die Methode wirkt nur auf die aktuelle Transformationsmatrix.

Besonders nützlich ist translate() zusammen mit rotate() und scale(): Wer ein Objekt um seinen eigenen Mittelpunkt drehen will, verschiebt den Ursprung zuerst an diesen Punkt, dreht danach und zeichnet das Objekt schließlich um (0, 0) herum. Außerdem vereinfacht die Methode das Zeichnen wiederverwendbarer Figuren, deren Koordinaten relativ zu einem lokalen Nullpunkt definiert sind, zum Beispiel Sprites, Diagrammachsen oder Kamera-Verschiebungen in Spielen.

Transformationen summieren sich: Zwei Aufrufe von translate(10, 0) verschieben den Ursprung insgesamt um 20 Pixel. Außerdem wirkt die Verschiebung im aktuellen, eventuell schon gedrehten oder skalierten Koordinatensystem. Deshalb klammert man Transformationen üblicherweise mit save() und restore() ein oder setzt die Matrix mit setTransform() bzw. resetTransform() zurück.

Mathematisch entspricht translate(x, y) dem Aufruf transform(1, 0, 0, 1, x, y).

Parameter

Name	Typ	Default	Beschreibung
$x Pflicht	number		Horizontale Verschiebung in Einheiten des aktuellen Koordinatensystems. Positive Werte verschieben nach rechts, negative nach links.
$y Pflicht	number		Vertikale Verschiebung in Einheiten des aktuellen Koordinatensystems. Positive Werte verschieben nach unten, negative nach oben.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Die Methode verändert die Transformationsmatrix des Kontexts.

Beispiele

Ursprung verschieben und Rechteck zeichnen

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

// Ohne Verschiebung: Rechteck oben links
ctx.fillStyle = 'lightgray';
ctx.fillRect(0, 0, 80, 50);

// Ursprung um 100 px nach rechts und 60 px nach unten verschieben
ctx.translate(100, 60);
ctx.fillStyle = 'tomato';
ctx.fillRect(0, 0, 80, 50); // landet bei (100, 60)

console.log(ctx.getTransform().e, ctx.getTransform().f);

100 60

Objekt um den eigenen Mittelpunkt drehen

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

const drawRotatedBox = (cx, cy, w, h, angleDeg) => {
  ctx.save();                          // Zustand sichern
  ctx.translate(cx, cy);               // Ursprung in den Mittelpunkt
  ctx.rotate((angleDeg * Math.PI) / 180);
  ctx.fillStyle = 'steelblue';
  ctx.fillRect(-w / 2, -h / 2, w, h);  // um (0,0) zentriert zeichnen
  ctx.restore();                       // Transformation zurücksetzen
};

drawRotatedBox(150, 100, 120, 60, 30);
drawRotatedBox(300, 100, 60, 60, 45);

Kamera-Verschiebung in einer Animationsschleife

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
const player = { x: 0, y: 120 };

const frame = () => {
  player.x += 2;

  // Matrix zurücksetzen, sonst summiert sich die Verschiebung jedes Frame
  ctx.setTransform(1, 0, 0, 1, 0, 0);
  ctx.clearRect(0, 0, canvas.width, canvas.height);

  // Kamera: Spieler bleibt horizontal in der Bildmitte
  ctx.translate(canvas.width / 2 - player.x, 0);

  // Welt zeichnen (Weltkoordinaten)
  for (let i = 0; i < 50; i++) {
    ctx.fillStyle = i % 2 ? '#ccc' : '#999';
    ctx.fillRect(i * 100, 150, 100, 20);
  }
  ctx.fillStyle = 'crimson';
  ctx.fillRect(player.x - 10, player.y, 20, 30);

  requestAnimationFrame(frame);
};

requestAnimationFrame(frame);

Pixelscharfe 1-px-Linien per halber Verschiebung

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

ctx.save();
ctx.translate(0.5, 0.5); // Linien liegen auf Pixelmitten statt Pixelkanten
ctx.lineWidth = 1;
ctx.strokeStyle = 'black';
ctx.beginPath();
ctx.moveTo(10, 10);
ctx.lineTo(200, 10);
ctx.stroke();
ctx.restore();

// Wichtig · Fallstricke

Kumulativ: Jeder Aufruf wird zur bestehenden Matrix hinzugerechnet. In Animationsschleifen die Matrix pro Frame mit setTransform(1, 0, 0, 1, 0, 0), resetTransform() oder save()/restore() zurücksetzen, sonst wandern die Objekte immer weiter weg.
Reihenfolge zählt: rotate() und danach translate() verschiebt entlang der gedrehten Achsen. translate() und danach rotate() dreht um den neuen Ursprung. Nach scale(2, 2) wird auch die Verschiebung verdoppelt.
clearRect(), fillRect(), drawImage() und isPointInPath() werden ebenfalls transformiert. Wer die ganze Fläche löschen will, sollte die Matrix vorher zurücksetzen.
Die Koordinaten von Mausereignissen werden nicht automatisch umgerechnet. Mit ctx.getTransform().invertSelf().transformPoint(new DOMPoint(x, y)) lassen sie sich in lokale Koordinaten umrechnen.
Nicht endliche Werte (NaN, Infinity) werden ohne Fehlermeldung ignoriert, und die Matrix bleibt unverändert.
Die Canvas-Größe ändert sich durch translate() nicht. Inhalte, die außerhalb der Fläche landen, werden abgeschnitten.
Kompatibilität: Die Methode wird von allen Browsern unterstützt und ist auch in OffscreenCanvasRenderingContext2D (Web Worker) verfügbar. getTransform() und resetTransform() sind neuer, gehören aber inzwischen ebenfalls zur Baseline.

Siehe auch

CanvasRenderingContext2D.rotate() CanvasRenderingContext2D.scale() CanvasRenderingContext2D.transform() CanvasRenderingContext2D.setTransform() CanvasRenderingContext2D.resetTransform() CanvasRenderingContext2D.getTransform() CanvasRenderingContext2D.save() CanvasRenderingContext2D.restore() CanvasRenderingContext2D