CanvasRenderingContext2D.strokeRect() — Methode · JavaScript-Referenz

Signatur

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

Beschreibung

strokeRect() zeichnet die Kontur eines Rechtecks direkt auf die Canvas. Die Position wird über die linke obere Ecke (x, y) angegeben, die Größe über width und height. Farbe bzw. Verlauf oder Muster kommen aus strokeStyle, die Strichstärke aus lineWidth. Außerdem wirken lineJoin, setLineDash(), globalAlpha, Schatten und die aktuelle Transformationsmatrix.

Anders als rect() mit anschließendem stroke() verändert strokeRect() den aktuellen Pfad nicht. Das Rechteck wird sofort gezeichnet und landet nicht im Pfad-Puffer. Deshalb eignet sich die Methode gut für schnelle Rahmen, Auswahlmarkierungen, Hilfslinien beim Debuggen oder Diagramm-Umrandungen, ohne dass ein laufender Pfad gestört wird.

Die Linie wird mittig auf der Rechteckkante gezeichnet: Bei lineWidth = 10 liegen 5 Pixel innerhalb und 5 Pixel außerhalb des Rechtecks. Für eine gefüllte Fläche gibt es fillRect(), zum Löschen eines Bereichs clearRect().

Parameter

Name	Typ	Beschreibung
$x Pflicht	number	x-Koordinate der linken oberen Ecke des Rechtecks (im aktuellen Koordinatensystem).
$y Pflicht	number	y-Koordinate der linken oberen Ecke des Rechtecks.
$width Pflicht	number	Breite des Rechtecks. Positive Werte gehen nach rechts, negative nach links.
$height Pflicht	number	Höhe des Rechtecks. Positive Werte gehen nach unten, negative nach oben.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Das Rechteck wird direkt auf die Canvas gezeichnet.

Beispiele

Einfacher Rahmen

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

ctx.strokeStyle = '#1e88e5';
ctx.lineWidth = 4;
// Rechteck bei (20, 20), 150 × 100 Pixel
ctx.strokeRect(20, 20, 150, 100);

Gestrichelter Auswahlrahmen per Maus

const canvas = document.querySelector('#leinwand');
const ctx = canvas.getContext('2d');
let start = null;

canvas.addEventListener('mousedown', (e) => {
  start = { x: e.offsetX, y: e.offsetY };
});

canvas.addEventListener('mousemove', (e) => {
  if (!start) return;
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.setLineDash([6, 4]);
  ctx.strokeStyle = 'rgb(0 0 0 / 0.7)';
  ctx.lineWidth = 1;
  // Negative Breite/Höhe sind erlaubt, wenn nach links/oben gezogen wird
  ctx.strokeRect(start.x + 0.5, start.y + 0.5, e.offsetX - start.x, e.offsetY - start.y);
});

canvas.addEventListener('mouseup', () => {
  start = null;
});

Scharfe 1-Pixel-Linien und der Pfad bleibt unverändert

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

// Ein Pfad wird aufgebaut ...
ctx.beginPath();
ctx.moveTo(10, 150);
ctx.lineTo(200, 150);

// ... strokeRect stört ihn nicht
ctx.lineWidth = 1;
ctx.strokeStyle = 'red';
ctx.strokeRect(10.5, 10.5, 100, 50); // +0.5 für scharfe Kanten

ctx.strokeStyle = 'black';
ctx.stroke(); // zeichnet nur die Linie, nicht das Rechteck

// Wichtig · Fallstricke

Unscharfe Linien: Die Kontur liegt mittig auf der Kante. Bei ungerader lineWidth auf ganzzahligen Koordinaten verteilt sich die Linie auf zwei Pixel und wirkt verschwommen. Abhilfe: Koordinaten um 0.5 verschieben. Auf HiDPI-Displays zusätzlich die Canvas mit devicePixelRatio skalieren.
Linie steht über: Die halbe Strichstärke ragt aus dem Rechteck heraus. Ein Rahmen direkt am Canvas-Rand wird deshalb teilweise abgeschnitten.
Größe 0: Ist nur width oder nur height gleich 0, entsteht eine einfache Linie. Sind beide 0, wird nichts gezeichnet. Nicht-endliche Werte wie NaN oder Infinity werden stillschweigend ignoriert.
strokeRect() berücksichtigt lineJoin, aber keine abgerundeten Ecken. Dafür gibt es roundRect() mit stroke() (neuer, inzwischen in allen aktuellen Browsern verfügbar).
Funktioniert auch mit OffscreenCanvasRenderingContext2D in Web Workern. Die Methode wird von allen Browsern unterstützt, auch von sehr alten.

Siehe auch

CanvasRenderingContext2D.fillRect() CanvasRenderingContext2D.clearRect() CanvasRenderingContext2D.rect() CanvasRenderingContext2D.stroke() CanvasRenderingContext2D.strokeStyle CanvasRenderingContext2D.lineWidth CanvasRenderingContext2D.setLineDash() CanvasRenderingContext2D.roundRect()