Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

Canvas 2D: salvare e ripristinare lo stato di disegno

`save()` inserisce lo stato di disegno corrente in una pila e `restore()` estrae e ripristina l’ultimo stato salvato. Nessuno dei due metodi annulla le modifiche ai pixel.

Versione: ECMAScript 2024 and the current web platform; runtime support varies

Sintassi

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

Chiama save() e restore() sullo stesso CanvasRenderingContext2D, per esempio ctx, ottenuto con canvas.getContext('2d'). Entrambi i metodi si chiamano senza argomenti e restituiscono undefined. Fanno parte dell’API web Canvas 2D, non di ECMAScript: un motore JavaScript da solo non ne garantisce la disponibilità.

save() inserisce una copia dello stato di disegno corrente nella pila del contesto. restore() estrae la voce in cima alla pila e la rende lo stato corrente. I salvataggi annidati vengono quindi ripristinati in ordine inverso: l’ultimo a entrare è il primo a uscire (LIFO). Se la pila è vuota, restore() non cambia nulla e non genera eccezioni.

Lo stato salvato include, tra le altre impostazioni, la matrice di trasformazione, la regione di ritaglio, gli stili di riempimento e del tratto e globalAlpha. Non include il tracciato predefinito corrente né i pixel del canvas: restore() non cancella ciò che hai disegnato e non annulla le modifiche al tracciato. Usa beginPath() per iniziare un nuovo tracciato predefinito.

Usa save() e restore() in coppia per limitare le modifiche a una parte del disegno. Se il codice intermedio può generare un’eccezione, chiama prima save(), inserisci quel codice in try e chiama restore() in finally per ripristinare lo stato anche in caso di eccezione.

Esempi

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

Risultato

0.25
0.5
1
0.125

Con due salvataggi annidati, la console mostra `0.25`, poi i valori ripristinati `0.5` e `1`. L’ultima chiamata a `restore()` trova la pila vuota, quindi `0.125` rimane invariato.

Lezioni correlate

  • JavaScript · Lezione 26 · Intermedio · Versione: 3

Fonti