CanvasRenderingContext2D.clearRect() — Methode · JavaScript-Referenz

Signatur

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

Beschreibung

Mit clearRect() löschen Sie einen rechteckigen Bereich auf einer 2D-Zeichenfläche. Alle Pixel in diesem Bereich werden auf transparentes Schwarz (rgba(0, 0, 0, 0)) gesetzt. Dahinterliegende CSS-Hintergründe oder Elemente der Seite werden dadurch wieder sichtbar.

Am häufigsten wird die Methode in Animationsschleifen eingesetzt: Vor jedem neuen Frame löschen Sie mit ctx.clearRect(0, 0, canvas.width, canvas.height) die komplette Zeichenfläche und zeichnen die Szene danach neu. Sie können aber auch gezielt nur einen Teilbereich löschen, zum Beispiel um ein bewegtes Objekt zu entfernen oder einen „Radierer“ umzusetzen.

Wichtig: clearRect() beachtet die aktuelle Transformationsmatrix (translate, scale, rotate) und die aktuelle Clipping-Region. Dagegen wird der aktuelle Pfad nicht verändert, und Einstellungen wie fillStyle, globalAlpha, globalCompositeOperation oder Schatten spielen keine Rolle.

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. Bei einem negativen Wert reicht das Rechteck nach links.
$height Pflicht	number	Höhe des Rechtecks. Bei einem negativen Wert reicht das Rechteck nach oben.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Teilbereich aus einer gefüllten Fläche löschen

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

// Gesamte Fläche blau füllen
ctx.fillStyle = 'steelblue';
ctx.fillRect(0, 0, 300, 150);

// Ein "Loch" in die Mitte schneiden
ctx.clearRect(100, 50, 100, 50);

// Pixel in der Mitte prüfen
const [r, g, b, a] = ctx.getImageData(150, 75, 1, 1).data;
console.log(r, g, b, a);

0 0 0 0

Animationsschleife: Canvas pro Frame leeren

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

const frame = () => {
  // Vorherigen Frame komplett löschen
  ctx.clearRect(0, 0, canvas.width, canvas.height);

  ctx.beginPath();
  ctx.arc(x, canvas.height / 2, 20, 0, Math.PI * 2);
  ctx.fillStyle = 'tomato';
  ctx.fill();

  x = (x + 2) % canvas.width;
  requestAnimationFrame(frame);
};

requestAnimationFrame(frame);

Trotz Transformation die ganze Fläche löschen

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

ctx.translate(50, 50);
ctx.scale(2, 2);
ctx.fillRect(0, 0, 40, 40);

// Transformation temporär zurücksetzen, sonst wird
// ein verschobener/skalierter Bereich gelöscht
ctx.save();
ctx.setTransform(1, 0, 0, 1, 0, 0);
ctx.clearRect(0, 0, canvas.width, canvas.height);
ctx.restore();

console.log(ctx.getTransform().a); // Skalierung bleibt erhalten

2

// Wichtig · Fallstricke

Pfad nicht vergessen: clearRect() setzt den aktuellen Pfad nicht zurück. Wenn Sie nach dem Löschen kein beginPath() aufrufen, zeichnet ein späteres fill() oder stroke() auch die alten Teilpfade erneut. Das ist ein klassischer Fehler in Animationen.
Transformationen: Ist eine Transformation aktiv, wird das Rechteck mit transformiert. Soll die ganze Fläche sicher gelöscht werden, setzen Sie die Matrix vorher mit setTransform(1, 0, 0, 1, 0, 0) zurück (siehe Beispiel 3). Bei Rotation wird ein gedrehter Bereich gelöscht.
Clipping: Gelöscht wird nur innerhalb der aktuellen Clipping-Region.
Übergeben Sie für die Ausmaße canvas.width/canvas.height (die Pixelauflösung) und nicht die CSS-Größe aus clientWidth. Wenn Sie für hochauflösende Displays mit devicePixelRatio skalieren, beachten Sie die Transformation.
Soll der Hintergrund nicht transparent, sondern einfarbig sein, verwenden Sie stattdessen fillRect() mit passendem fillStyle. Wurde der Kontext mit { alpha: false } erzeugt, erscheinen gelöschte Pixel schwarz statt transparent.
Alternativ setzt canvas.width = canvas.width den gesamten Kontext zurück, also auch alle Zustände wie Stile und Transformationen. Das ist meist langsamer und selten gewollt. Moderne Browser bieten dafür auch ctx.reset() an.
Wird für einen der Parameter Infinity oder NaN übergeben, wird der Aufruf still ignoriert.
Die Methode wird von allen Browsern unterstützt, auch von OffscreenCanvasRenderingContext2D in Web Workern.

Siehe auch

CanvasRenderingContext2D.fillRect() CanvasRenderingContext2D.strokeRect() CanvasRenderingContext2D.beginPath() CanvasRenderingContext2D.setTransform() CanvasRenderingContext2D.reset() requestAnimationFrame() CanvasRenderingContext2D