Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

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

Fontes