CKTIS / JavaScript
Canvas 2D : enregistrer et restaurer l’état de dessin
`save()` empile l’état de dessin courant, tandis que `restore()` dépile et rétablit le dernier état enregistré. Ces méthodes n’annulent pas les modifications de pixels.
Version : ECMAScript 2024 and the current web platform; runtime support varies
Syntaxe
ctx.save();
ctx.restore();Appelez save() et restore() sur le même CanvasRenderingContext2D, par exemple ctx, obtenu avec canvas.getContext('2d'). Ces méthodes ne prennent aucun argument et renvoient undefined. Elles font partie de l’API web Canvas 2D, et non d’ECMAScript : la présence d’un moteur JavaScript ne garantit donc pas leur disponibilité.
save() empile une copie de l’état de dessin courant sur la pile du contexte. restore() dépile l’entrée du sommet et en fait l’état courant. Les enregistrements imbriqués sont donc restaurés en ordre inverse : dernier entré, premier sorti (LIFO). Si la pile est vide, restore() ne change rien et ne lève pas d’exception.
L’état enregistré comprend notamment la matrice de transformation, la zone de découpage, les styles de remplissage et de contour, ainsi que globalAlpha. Il ne comprend ni le tracé courant par défaut ni les pixels du canevas : restore() n’efface pas le dessin et n’annule pas les modifications du tracé. Utilisez beginPath() pour commencer un nouveau tracé par défaut.
Associez save() et restore() pour limiter les changements à une partie du dessin. Si le code intermédiaire risque de lever une exception, appelez d’abord save(), placez ce code dans try et appelez restore() dans finally pour rétablir l’état même en cas d’exception.
Exemples
<!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>Résultat
0.25 0.5 1 0.125
Avec deux enregistrements imbriqués, la console affiche `0.25`, puis les valeurs restaurées `0.5` et `1`. Au dernier appel à `restore()`, la pile est vide : `0.125` ne change donc pas.
Leçons associées
- JavaScript · Leçon 26 · Intermédiaire · Version : 3