CanvasRenderingContext2D.roundRect() — Methode · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.prototype.roundRect(x, y, width, height, radii)

Beschreibung

roundRect() fügt dem aktuellen Pfad des 2D-Kontexts ein abgerundetes Rechteck als eigenen, geschlossenen Teilpfad hinzu. Wie bei rect() wird dabei noch nichts gezeichnet. Sichtbar wird die Form erst durch fill() oder stroke(). Mit clip() lässt sie sich außerdem als Ausschnittmaske verwenden.

Die Methode ersetzt die früher übliche Handarbeit mit arcTo() oder quadraticCurveTo(). Typische Einsatzfälle sind Buttons, Karten, Sprechblasen, Balken in Diagrammen, Fortschrittsbalken und abgerundete Bildausschnitte.

Der Parameter radii funktioniert ähnlich wie die CSS-Eigenschaft border-radius. Er nimmt eine einzelne Zahl oder eine Liste mit 1 bis 4 Werten an. Die Werte gelten im Uhrzeigersinn ab oben links: oben links, oben rechts, unten rechts, unten links. Jeder Wert kann eine Zahl sein oder ein DOMPointInit-Objekt {x, y} für elliptische Ecken. Sind die Radien zu groß für das Rechteck, werden alle Radien gemeinsam herunterskaliert, genau wie in CSS.

Negative Werte für width oder height sind erlaubt. Das Rechteck wird dann in die entgegengesetzte Richtung gezeichnet, und die Radien werden passend gespiegelt. Die Methode gibt es auch auf Path2D und OffscreenCanvasRenderingContext2D.

Parameter

Name	Typ	Default	Beschreibung
$x Pflicht	number		x-Koordinate der Startecke des Rechtecks (normalerweise oben links).
$y Pflicht	number		y-Koordinate der Startecke des Rechtecks.
$width Pflicht	number		Breite des Rechtecks. Ein negativer Wert zeichnet nach links.
$height Pflicht	number		Höhe des Rechtecks. Ein negativer Wert zeichnet nach oben.
$radii	number \| DOMPointInit \| Array<number \| DOMPointInit>	0	Eckradien, wie bei `border-radius`. Möglich sind ein einzelner Wert für alle Ecken oder eine Liste mit 1–4 Werten: `[a]`: alle Ecken `[a, b]`: oben links + unten rechts / oben rechts + unten links `[a, b, c]`: oben links / oben rechts + unten links / unten rechts `[a, b, c, d]`: oben links, oben rechts, unten rechts, unten links Ein `{x, y}`-Objekt erzeugt elliptische Ecken.

Rückgabewert

Typ

void

Beschreibung

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

Beispiele

Einfacher abgerundeter Button

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

ctx.beginPath();
ctx.roundRect(20, 20, 160, 48, 12);
ctx.fillStyle = '#2563eb';
ctx.fill();

ctx.fillStyle = '#fff';
ctx.font = '600 18px system-ui';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.fillText('Speichern', 100, 44);

Unterschiedliche Radien je Ecke (Sprechblase / Tab)

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

// oben links, oben rechts, unten rechts, unten links
ctx.beginPath();
ctx.roundRect(20, 20, 200, 80, [16, 16, 16, 0]);
ctx.fillStyle = '#e5e7eb';
ctx.fill();

// elliptische Ecken per {x, y}
ctx.beginPath();
ctx.roundRect(20, 120, 200, 60, [{ x: 40, y: 15 }]);
ctx.strokeStyle = '#111';
ctx.lineWidth = 2;
ctx.stroke();

Balkendiagramm mit oben abgerundeten Balken

const ctx = document.querySelector('canvas').getContext('2d');
const werte = [120, 80, 150, 60, 110];
const basisY = 200;

ctx.fillStyle = '#10b981';
ctx.beginPath();
werte.forEach((wert, i) => {
  // Mehrere Teilpfade in einem Pfad sammeln, dann einmal füllen
  ctx.roundRect(20 + i * 50, basisY - wert, 36, wert, [8, 8, 0, 0]);
});
ctx.fill();

Bild abgerundet zuschneiden mit clip() und Fallback

const ctx = document.querySelector('canvas').getContext('2d');
const img = new Image();
img.src = 'avatar.jpg';
await img.decode();

ctx.save();
ctx.beginPath();
if (typeof ctx.roundRect === 'function') {
  ctx.roundRect(10, 10, 128, 128, 24);
} else {
  ctx.rect(10, 10, 128, 128); // Fallback für alte Browser
}
ctx.clip();
ctx.drawImage(img, 10, 10, 128, 128);
ctx.restore();

// Wichtig · Fallstricke

beginPath() nicht vergessen: roundRect() hängt an den bestehenden Pfad an. Ohne vorheriges beginPath() werden alte Formen bei jedem fill()/stroke() erneut gezeichnet.
Fehler bei ungültigen Radien: Negative Radien lösen einen RangeError aus, ebenso eine Liste mit 0 oder mehr als 4 Einträgen. Enthalten Argumente NaN oder Infinity, wird der Aufruf still ignoriert.
Zu große Radien: Summieren sich die Radien auf einer Seite zu mehr als deren Länge, werden alle Radien gleichmäßig verkleinert. Mit radii = height / 2 entsteht so zuverlässig eine Pillenform.
Browser-Kompatibilität: Unterstützt seit Chrome/Edge 99, Safari 16 und Firefox 112 (Baseline 2023). Für ältere Browser per typeof ctx.roundRect === 'function' prüfen und auf arcTo() ausweichen oder ein Polyfill einsetzen.
Der Teilpfad ist nach dem Aufruf bereits geschlossen. Ein zusätzliches closePath() ist nicht nötig.

Siehe auch

CanvasRenderingContext2D.rect() CanvasRenderingContext2D.arcTo() CanvasRenderingContext2D.beginPath() CanvasRenderingContext2D.fill() CanvasRenderingContext2D.stroke() CanvasRenderingContext2D.clip() CanvasRenderingContext2D