CanvasRenderingContext2D.reset() — Methode · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.prototype.reset()

Beschreibung

reset() bringt einen CanvasRenderingContext2D in den Zustand zurück, den er direkt nach canvas.getContext("2d") hatte. Die Methode löscht dabei:

die Bitmap: alle Pixel werden transparent schwarz,
den aktuellen Pfad (wie beginPath()),
den Zustands-Stack, der mit save() aufgebaut wurde,
die Transformationsmatrix (wieder Einheitsmatrix) und die Beschneidungsbereiche (Clipping),
alle Zeicheneinstellungen wie fillStyle, strokeStyle, lineWidth, font, globalAlpha, filter, shadow* und Linienstriche (setLineDash).

Bisher hat man dafür canvas.width = canvas.width gesetzt. Dieser Trick hat denselben Effekt, lässt die Absicht aber nicht erkennen und kann den Canvas unnötig neu anlegen. reset() ist der ausdrückliche und lesbare Weg dafür, und die Größe des Canvas bleibt unverändert.

Die Methode eignet sich zum Wiederverwenden eines Canvas oder OffscreenCanvas für ganz andere Inhalte, zum Beispiel wenn eine Diagramm-Bibliothek den Diagrammtyp wechselt oder ein Worker immer neue Kacheln rendert. Auch nach Fehlern mit unausgeglichenen save()/restore()-Aufrufen hilft sie. Für das normale Löschen pro Animations-Frame reicht meist clearRect(), das die Einstellungen beibehält.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Einfaches Zurücksetzen nach dem Zeichnen

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

ctx.fillStyle = "crimson";
ctx.lineWidth = 8;
ctx.translate(50, 50);
ctx.fillRect(0, 0, 100, 60);

ctx.reset();

// Alles wieder auf Standardwerte
console.log(ctx.fillStyle);   // Standardfarbe
console.log(ctx.lineWidth);   // Standardbreite
console.log(ctx.getTransform().isIdentity);

#000000 1 true

Unausgeglichene save()-Aufrufe aufräumen

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

const drawBadge = (text) => {
  ctx.save();
  ctx.font = "bold 20px sans-serif";
  ctx.fillStyle = "teal";
  ctx.beginPath();
  ctx.arc(60, 60, 50, 0, Math.PI * 2);
  ctx.clip();
  ctx.fillRect(0, 0, 120, 120);
  ctx.fillStyle = "white";
  ctx.fillText(text, 30, 68);
  // restore() vergessen: Clipping und Stil bleiben aktiv!
};

drawBadge("Neu");

// Statt nach dem Fehler zu suchen: Kontext komplett zurücksetzen
ctx.reset();
ctx.fillRect(150, 10, 80, 80); // wird nicht mehr weggeschnitten, Farbe wieder Schwarz

Wiederverwendeter OffscreenCanvas in einem Worker

// worker.js
const offscreen = new OffscreenCanvas(256, 256);
const ctx = offscreen.getContext("2d");

self.onmessage = async ({ data }) => {
  ctx.reset(); // saubere Ausgangslage für jede Kachel

  ctx.fillStyle = data.color;
  ctx.fillRect(0, 0, 256, 256);
  ctx.font = "24px monospace";
  ctx.fillStyle = "black";
  ctx.fillText(`${data.x}/${data.y}`, 20, 40);

  const blob = await offscreen.convertToBlob({ type: "image/png" });
  self.postMessage({ id: data.id, blob });
};

Mit Fallback für ältere Browser

const resetContext = (ctx) => {
  if (typeof ctx.reset === "function") {
    ctx.reset();
  } else {
    // Klassischer Trick: Größe neu setzen leert Bitmap und Zustand
    const { canvas } = ctx;
    canvas.width = canvas.width;
  }
};

const ctx = document.querySelector("canvas").getContext("2d");
ctx.fillRect(0, 0, 50, 50);
resetContext(ctx);

// Wichtig · Fallstricke

Browser-Unterstützung: Erst seit 2023 in allen großen Engines verfügbar (Chrome/Edge 99, Firefox 113, Safari 18). Für ältere Browser zuerst mit typeof ctx.reset === "function" prüfen und notfalls canvas.width = canvas.width verwenden.
Nicht mit clearRect() verwechseln: clearRect() löscht nur Pixel und beachtet dabei Transformation und Clipping. reset() setzt dagegen alle Einstellungen zurück. In einer Animationsschleife müsstest du nach reset() jeden Stil neu setzen, was unnötig Arbeit kostet.
HiDPI-Skalierung geht verloren: Ein mit ctx.scale(devicePixelRatio, devicePixelRatio) eingerichteter Maßstab wird ebenfalls zurückgesetzt und muss danach neu angewendet werden.
Die Größe des Canvas (width/height) und die bei getContext() übergebenen Optionen (z. B. alpha, willReadFrequently) bleiben erhalten.
Auch in OffscreenCanvasRenderingContext2D vorhanden und damit in Web Workern nutzbar.

Siehe auch

CanvasRenderingContext2D CanvasRenderingContext2D.clearRect() CanvasRenderingContext2D.save() CanvasRenderingContext2D.restore() CanvasRenderingContext2D.resetTransform() OffscreenCanvas CanvasRenderingContext2D.ellipse()