CKTIS / JavaScript
Canvas 2D: Zeichenzustand speichern und wiederherstellen
`save()` legt den aktuellen Zeichenzustand auf einen Stapel. `restore()` nimmt den zuletzt gespeicherten Zustand vom Stapel und stellt ihn wieder her. Pixeländerungen bleiben bestehen.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
ctx.save();
ctx.restore();Rufe save() und restore() auf demselben CanvasRenderingContext2D auf, etwa auf ctx aus canvas.getContext('2d'). Beide Methoden erwarten keine Argumente und geben undefined zurück. Sie gehören zur Canvas-2D-Web-API, nicht zu ECMAScript. Eine JavaScript-Engine allein garantiert daher nicht, dass sie verfügbar sind.
save() legt eine Kopie des aktuellen Zeichenzustands auf den Stapel des Kontexts. restore() entfernt den obersten Eintrag und macht ihn zum aktuellen Zustand. Verschachtelt gespeicherte Zustände werden also in umgekehrter Reihenfolge wiederhergestellt: zuletzt gespeichert, zuerst wiederhergestellt (LIFO). Ist der Stapel leer, ändert restore() nichts und löst keine Ausnahme aus.
Zum gespeicherten Zustand gehören unter anderem die Transformationsmatrix, der Beschneidungsbereich, die Füll- und Konturstile sowie globalAlpha. Der aktuelle Standardpfad und die Pixel der Zeichenfläche gehören nicht dazu: restore() löscht nichts Gezeichnetes und macht keine Pfadänderungen rückgängig. Mit beginPath() beginnst du einen neuen Standardpfad.
Verwende save() und restore() als Paar, wenn Änderungen nur einen Teil der Zeichnung betreffen sollen. Kann der Code dazwischen eine Ausnahme auslösen, rufe zuerst save() auf, setze den Code in try und rufe restore() in finally auf. So wird der Zustand auch bei einer Ausnahme wiederhergestellt.
Beispiele
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Canvas 2D: save and restore</title>
</head>
<body>
<canvas id="canvas" width="1" height="1" hidden></canvas>
<script>
(() => {
const ctx = document.getElementById("canvas").getContext("2d");
if (!ctx) throw new Error("Canvas 2D is unavailable.");
ctx.globalAlpha = 1;
ctx.save();
ctx.globalAlpha = 0.5;
ctx.save();
ctx.globalAlpha = 0.25;
console.log(ctx.globalAlpha);
ctx.restore();
console.log(ctx.globalAlpha);
ctx.restore();
console.log(ctx.globalAlpha);
ctx.globalAlpha = 0.125;
ctx.restore(); // The stack is empty.
console.log(ctx.globalAlpha);
})();
</script>
</body>
</html>Ergebnis
0.25 0.5 1 0.125
Bei zwei verschachtelten Speicherungen gibt die Konsole zuerst `0.25` aus, dann die wiederhergestellten Werte `0.5` und `1`. Beim letzten `restore()` ist der Stapel leer, daher bleibt `0.125` unverändert.
Zugehörige Lektionen
- JavaScript · Lektion 26 · Mittlere Stufe · Version: 3