CanvasRenderingContext2D.rect() — Methode · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.prototype.rect(x, y, width, height)

Beschreibung

Die Methode rect() der Canvas 2D API fügt dem aktuellen Pfad ein Rechteck hinzu. Die linke obere Ecke liegt bei (x, y), die Größe wird durch width und height festgelegt. Das Rechteck bildet einen eigenen, bereits geschlossenen Teilpfad. Anders als fillRect() oder strokeRect() wird dabei noch nichts gezeichnet. Sichtbar wird es erst durch fill() oder stroke().

Sinnvoll ist rect() vor allem, wenn mehrere Formen zu einem Pfad zusammengefasst werden sollen, etwa um viele Rechtecke mit einem einzigen fill()-Aufruf zu zeichnen, um einen Clipping-Bereich mit clip() festzulegen oder um mit isPointInPath() Treffer zu prüfen.

Intern entspricht der Aufruf etwa der Folge moveTo(x, y), drei lineTo()-Aufrufen und closePath(). Danach steht der aktuelle Punkt wieder bei (x, y). Negative Werte für Breite oder Höhe sind erlaubt: Das Rechteck wird dann nach links bzw. nach oben aufgespannt.

Parameter

Name	Typ	Beschreibung
$x Pflicht	number	x-Koordinate der Startecke (normalerweise links oben) im aktuellen Koordinatensystem.
$y Pflicht	number	y-Koordinate der Startecke.
$width Pflicht	number	Breite des Rechtecks. Ein negativer Wert spannt das Rechteck nach links auf.
$height Pflicht	number	Höhe des Rechtecks. Ein negativer Wert spannt das Rechteck nach oben auf.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Die Methode verändert nur den aktuellen Pfad des Kontexts.

Beispiele

Rechteck anlegen, füllen und umranden

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

ctx.beginPath();
ctx.rect(20, 20, 150, 100);
ctx.fillStyle = '#4caf50';
ctx.fill();
ctx.lineWidth = 4;
ctx.strokeStyle = '#1b5e20';
ctx.stroke();

Viele Balken mit nur einem fill()-Aufruf zeichnen

const ctx = document.querySelector('canvas').getContext('2d');
const werte = [40, 90, 65, 120, 30];
const balkenBreite = 30;

ctx.beginPath();
werte.forEach((wert, i) => {
  // Balken wachsen von der Grundlinie y = 150 nach oben (negative Höhe)
  ctx.rect(10 + i * (balkenBreite + 10), 150, balkenBreite, -wert);
});
ctx.fillStyle = 'steelblue';
ctx.fill(); // ein Zeichenaufruf für alle Balken

Rechteckigen Clipping-Bereich festlegen

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

ctx.save();
ctx.beginPath();
ctx.rect(50, 50, 100, 100);
ctx.clip(); // Ab hier wird nur noch innerhalb des Rechtecks gezeichnet

ctx.fillStyle = 'tomato';
ctx.beginPath();
ctx.arc(100, 100, 80, 0, Math.PI * 2);
ctx.fill();
ctx.restore(); // Clipping wieder aufheben

Trefferprüfung mit isPointInPath()

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

ctx.beginPath();
ctx.rect(30, 30, 120, 60);
ctx.fill();

canvas.addEventListener('click', (e) => {
  const { left, top } = canvas.getBoundingClientRect();
  const treffer = ctx.isPointInPath(e.clientX - left, e.clientY - top);
  console.log(treffer ? 'Button getroffen' : 'daneben');
});

Button getroffen

// Wichtig · Fallstricke

beginPath() nicht vergessen: Ohne neuen Pfad sammeln sich alle bisherigen Formen an und werden bei jedem fill()/stroke() erneut gezeichnet. Das kostet Leistung und kann zu dunkleren Rändern führen, weil halbtransparente Linien mehrfach übereinander liegen.
Kein sofortiges Zeichnen: Soll nur ein einzelnes Rechteck erscheinen, sind fillRect() bzw. strokeRect() kürzer. Beide verändern den aktuellen Pfad nicht.
Scharfe 1-px-Linien: Bei lineWidth = 1 wirken Linien auf ganzzahligen Koordinaten verschwommen. Um 0,5 px verschobene Koordinaten (z. B. rect(10.5, 10.5, 100, 50)) sorgen für scharfe Kanten.
Sind Argumente Infinity oder NaN, wird der Aufruf still ignoriert. Es gibt keinen Fehler.
Die aktuelle Transformation (translate(), rotate(), scale()) wirkt auf das Rechteck. Gedreht entsteht so ein Parallelogramm oder ein gedrehtes Rechteck.
Für abgerundete Ecken gibt es roundRect(), in allen modernen Browsern verfügbar seit 2023. Dieselbe Methode gibt es auch auf Path2D und OffscreenCanvasRenderingContext2D.

Siehe auch

CanvasRenderingContext2D.fillRect() CanvasRenderingContext2D.strokeRect() CanvasRenderingContext2D.roundRect() CanvasRenderingContext2D.beginPath() CanvasRenderingContext2D.fill() CanvasRenderingContext2D.stroke() CanvasRenderingContext2D.clip()