Web Animations API
Scopri come utilizzare la Web Animations API per creare animazioni fluide e controllabili direttamente con JavaScript, senza librerie esterne.
La Web Animations API
La Web Animations API (WAAPI) consente di creare e controllare animazioni direttamente da JavaScript, senza librerie esterne. Le animazioni vengono eseguite sul compositor nativo del browser — lo stesso motore che alimenta le animazioni CSS — garantendo un movimento fluido con accelerazione hardware, ma con il controllo programmatico delle animazioni JavaScript: puoi avviare, mettere in pausa, invertire, accelerare, cercare e concatenare animazioni in fase di esecuzione.
Questa pagina illustra i due elementi fondamentali: il metodo element.animate() che avvia un'animazione, e l'oggetto Animation che restituisce, utilizzato per controllare la riproduzione e sapere quando l'animazione termina.
element.animate(keyframes, options)
Ogni animazione WAAPI inizia con una singola chiamata:
const animation = element.animate(keyframes, options);keyframes— gli stati visivi attraverso cui passare. Sono accettate due forme:- un array di object, dove ogni object rappresenta un fotogramma:
[{ opacity: 0 }, { opacity: 1 }] - un object di array, dove ogni proprietà elenca i propri valori lungo la timeline:
{ opacity: [0, 1] }
- un array di object, dove ogni object rappresenta un fotogramma:
options— può essere un numero (la durata in millisecondi) oppure un oggetto timing come{ duration: 1000, easing: "ease-in-out", fill: "forwards" }.
La chiamata restituisce un oggetto Animation e inizia immediatamente la riproduzione. I nomi delle proprietà usano la forma CSS in camelCase (backgroundColor, non background-color).
Animazione di base con la Web Animations API
Creare un'animazione di base con la Web Animations API comporta la definizione dei keyframe dell'animazione, l'individuazione dell'elemento target e la configurazione delle opzioni. Ecco un esempio semplificato di animazione dell'opacità di un elemento:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Simple Opacity Animation</title>
</head>
<body>
<h1>Simple Opacity Animation</h1>
<div
class="animated-element"
style="width: 100px; height: 100px; background-color: blue"
></div>
<button style="margin-top: 15px" onclick="startAnimation()">
Start Animation
</button>
<p id="message"></p>
<script>
let animation;
function startAnimation() {
const element = document.querySelector(".animated-element");
const keyframes = [
{ opacity: 0, offset: 0 },
{ opacity: 1, offset: 1 },
];
const options = {
duration: 1000,
easing: "ease-in-out",
iterations: 1,
fill: "forwards",
};
// Create and play the animation
animation = element.animate(keyframes, options);
// Handle animation events
animation.onfinish = () => {
document.getElementById("message").textContent =
"Animation finished!";
};
animation.oncancel = () => {
document.getElementById("message").textContent = "Animation reset.";
};
}
// Resets the animation
function resetAnimation() {
if (animation) {
animation.cancel();
}
startAnimation(); // Restart the animation
}
</script>
</body>
</html>Questo esempio mostra come animare l'opacità di un elemento usando la Web Animations API. Un pulsante avvia l'animazione, che modifica gradualmente l'opacità dell'elemento da invisibile (0) a completamente visibile (1). Al termine dell'animazione, viene mostrato un messaggio all'utente. Questo illustra il controllo di base delle animazioni e la gestione degli eventi.
Opzioni di timing
Il secondo argomento di animate() controlla come l'animazione scorre nel tempo. Le chiavi più utili sono:
| Opzione | Descrizione |
|---|---|
duration | Durata di un'iterazione, in millisecondi (o una stringa di tempo CSS come "1s"). |
iterations | Numero di ripetizioni. Usa Infinity per eseguire un loop continuo. |
easing | La curva di accelerazione: "linear", "ease", "ease-in-out", oppure un cubic-bezier(...). |
fill | Lo stato da mantenere al di fuori dell'intervallo attivo. "forwards" mantiene l'ultimo fotogramma; "backwards" applica il primo fotogramma durante il delay; "both" fa entrambe le cose. |
delay | Millisecondi di attesa prima dell'avvio. |
direction | "normal", "reverse", oppure "alternate" (avanti e indietro a ogni iterazione). |
Senza fill: "forwards", un elemento torna bruscamente ai suoi stili originali non appena l'animazione termina — una fonte comune di confusione. Impostalo quando il fotogramma finale deve rimanere visibile.
L'oggetto Animation
element.animate() restituisce un'istanza di Animation. Questo è l'handle che si usa dopo che l'animazione è stata avviata:
| Membro | Scopo |
|---|---|
play() | Avvia o riprende la riproduzione. |
pause() | Congela nel punto corrente. |
reverse() | Esegue dal punto corrente verso l'inizio. |
finish() | Salta direttamente alla fine (o all'inizio, se invertita). |
cancel() | Interrompe e rimuove tutti gli effetti, eliminando gli stili applicati. |
finished | Una Promise che si risolve al completamento dell'animazione — ideale per la sequenziazione con await. |
playState | "running", "paused", "finished", oppure "idle". |
playbackRate | Moltiplicatore di velocità; 2 è velocità doppia, -1 riproduce al contrario. |
const anim = box.animate({ transform: ["translateX(0)", "translateX(200px)"] }, 1000);
anim.pause(); // hold in place
anim.playbackRate = 2; // play twice as fast when resumed
anim.play();
anim.finished.then(() => console.log(anim.playState)); // "finished"Poiché finished è una vera Promise, puoi usare await per eseguire del codice solo al termine del movimento, oppure per concatenare animazioni in modo pulito — come fa l'esempio successivo.
Animazioni complesse e sequenze
Per animazioni e sequenze più complesse, puoi concatenare più animazioni usando promise e async/await. Ecco un esempio di concatenazione di animazioni:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Animation Sequence</title>
</head>
<body>
<h1>Animation Sequence</h1>
<div
class="animated-element"
style="width: 100px; height: 100px; background-color: red"
></div>
<button style="margin-top: 15px" onclick="animateSequence()">
Start Animation
</button>
<p id="message"></p>
<script>
async function animateSequence() {
document.getElementById("message").textContent = ""; // Clear message
const element = document.querySelector(".animated-element");
const animation1 = element.animate(
{ opacity: [0, 1], transform: ["scale(0)", "scale(1)"] },
{ duration: 1000, easing: "ease-in-out" }
);
await animation1.finished;
const animation2 = element.animate(
{ opacity: [1, 0], transform: ["scale(1)", "scale(0)"] },
{ duration: 1000, easing: "ease-in-out" }
);
await animation2.finished;
document.getElementById("message").textContent = "Sequence complete!";
}
</script>
</body>
</html>In questo esempio, la prima animazione aumenta l'opacità dell'elemento e lo ingrandisce; al suo completamento, la seconda animazione lo sfuma e lo riduce. Al termine viene mostrato un messaggio di completamento, dimostrando come concatenare animazioni in sequenza.
Controllo e gestione delle animazioni
La Web Animations API fornisce anche metodi per controllare e gestire le animazioni. Ad esempio, puoi mettere in pausa, riprendere o annullare un'animazione. Ecco un esempio di come mettere in pausa e riprendere un'animazione:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Toggle Animation Play/Pause</title>
</head>
<body>
<h1>Toggle Play/Pause Animation</h1>
<div
class="animated-element"
style="width: 100px; height: 100px; background-color: green"
></div>
<button style="margin-top: 15px" onclick="togglePlayPause()">Toggle Play/Pause</button>
<p id="message"></p>
<script>
let animation;
document.addEventListener("DOMContentLoaded", function () {
const element = document.querySelector(".animated-element");
animation = element.animate(
{ opacity: [0, 1] },
{
duration: 1000,
easing: "ease-in-out",
iterations: Infinity,
direction: "alternate"
}
);
animation.pause(); // Start paused
animation.onfinish = () => {
document.getElementById("message").textContent =
"Animation finished!";
};
});
function togglePlayPause() {
if (animation.playState === "running") {
animation.pause();
document.getElementById("message").textContent = "Animation paused";
} else {
animation.play();
document.getElementById("message").textContent = "Animation playing";
}
}
</script>
</body>
</html>Questo esempio mostra come alternare gli stati di riproduzione e pausa di un'animazione con un clic. L'animazione iniziale fa sfumare continuamente un elemento. Cliccando un pulsante, l'utente può mettere in pausa l'animazione se è in esecuzione, oppure riprodurla se è in pausa. I messaggi indicano lo stato corrente dell'animazione, migliorando l'interazione dell'utente e il controllo sugli stati delle animazioni.
Web Animations API vs animazioni CSS
Entrambe girano sullo stesso compositor, quindi le prestazioni sono paragonabili. La differenza sta nel controllo:
- Scegli le animazioni CSS quando il movimento è dichiarativo e statico — un effetto hover, uno spinner di caricamento, una transizione d'ingresso definibile interamente in un foglio di stile.
- Scegli la Web Animations API quando l'animazione dipende da dati in fase di esecuzione o dall'input dell'utente: valori di keyframe dinamici, pausa e ripresa su richiesta, sequenziamento di più animazioni, o reazione al completamento di un'animazione tramite la promise
finished.
Un utile punto di equilibrio è mantenere lo stile nelle classi — vedi Stili e classi — e usare WAAPI solo per le transizioni che richiedono controllo tramite script.
Conclusione
La Web Animation API mette in mano agli sviluppatori web gli strumenti per creare animazioni accattivanti e interattive che migliorano l'esperienza utente su siti e applicazioni web. Padroneggiando questa API, puoi realizzare animazioni che spaziano da semplici transizioni a sequenze complesse, aggiungendo una dimensione dinamica e coinvolgente ai tuoi design web. Che tu stia animando interfacce utente, aggiungendo effetti visivi o creando elementi narrativi interattivi, la Web Animations API ti fornisce gli strumenti necessari per dare vita alle tue idee creative sul web.