Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

Canvas 2D: guardar y restaurar el estado de dibujo

`save()` guarda el estado de dibujo actual en una pila y `restore()` extrae y restablece el último estado guardado. Ninguno de los dos métodos deshace cambios en los píxeles.

Versión: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxis

ctx.save();
ctx.restore();

Llama a save() y restore() sobre el mismo CanvasRenderingContext2D, por ejemplo, ctx, obtenido con canvas.getContext('2d'). Ambos métodos se llaman sin argumentos y devuelven undefined. Forman parte de la API web Canvas 2D, no de ECMAScript; disponer de un motor de JavaScript no garantiza que estén disponibles.

save() coloca una copia del estado de dibujo actual en la pila del contexto. restore() extrae la entrada superior y la convierte en el estado actual. Los estados guardados de forma anidada se restauran en orden inverso: el último en entrar es el primero en salir (LIFO). Si la pila está vacía, restore() no cambia nada ni lanza una excepción.

El estado guardado incluye, entre otros elementos, la matriz de transformación, la región de recorte, los estilos de relleno y de trazo, y globalAlpha. No incluye el trazado predeterminado actual ni los píxeles del lienzo: restore() no borra lo dibujado ni deshace cambios en ese trazado. Usa beginPath() para iniciar un nuevo trazado predeterminado.

Usa save() y restore() en pareja para limitar los cambios a una parte del dibujo. Si el código intermedio puede lanzar una excepción, llama primero a save(), coloca ese código en try y llama a restore() en finally para recuperar el estado incluso si se produce una excepción.

Ejemplos

<!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

Con dos guardados anidados, la consola muestra `0.25` y luego los valores restaurados `0.5` y `1`. La última llamada a `restore()` encuentra la pila vacía y deja `0.125` sin cambios.

Lecciones relacionadas

  • JavaScript · Lección 26 · Intermedio · Versión: 3

Fuentes