CKTIS / JavaScript
Canvas 2D: guardar e repor o estado de desenho
`save()` coloca o estado de desenho atual numa pilha e `restore()` retira e repõe o último estado guardado. Nenhum dos métodos desfaz alterações nos píxeis.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
ctx.save();
ctx.restore();Chama save() e restore() no mesmo CanvasRenderingContext2D, por exemplo, em ctx, obtido com canvas.getContext('2d'). Ambos os métodos são chamados sem argumentos e devolvem undefined. Fazem parte da API Web Canvas 2D, não de ECMAScript; um motor de JavaScript, só por si, não garante que estejam disponíveis.
save() coloca uma cópia do estado de desenho atual na pilha do contexto. restore() retira a entrada do topo e torna-a o estado atual. Os estados guardados de forma aninhada são, por isso, repostos por ordem inversa: o último a entrar é o primeiro a sair (LIFO). Se a pilha estiver vazia, restore() não altera nada nem lança uma exceção.
O estado guardado inclui, entre outras definições, a matriz de transformação, a região de recorte, os estilos de preenchimento e de contorno e globalAlpha. Não inclui o caminho predefinido atual nem os píxeis da área de desenho: restore() não apaga o que foi desenhado nem desfaz alterações ao caminho. Usa beginPath() para iniciar um novo caminho predefinido.
Usa save() e restore() em par para limitar as alterações a uma parte do desenho. Se o código entre as duas chamadas puder lançar uma exceção, chama primeiro save(), coloca esse código em try e chama restore() em finally para repor o estado mesmo que ocorra uma exceção.
Exemplos
<!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>Resultado
0.25 0.5 1 0.125
Com dois estados guardados de forma aninhada, a consola mostra `0.25` e depois os valores repostos `0.5` e `1`. Na última chamada a `restore()`, a pilha está vazia, pelo que `0.125` se mantém.
Lições relacionadas
- JavaScript · Lição 26 · Intermédio · Versão: 3