Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

WAAPI: array di fotogrammi chiave e opzioni temporali

Passa un array di fotogrammi chiave a `Element.animate()` e usa un oggetto di opzioni separato per impostare durata, progressione e numero di iterazioni.

Versione: Current web platform; runtime support varies

Sintassi

element.animate(keyframes, { duration, easing, iterations })
element.animate(keyframes, duration)

element.animate(keyframes, options) crea e avvia un’animazione su un elemento del DOM e restituisce l’oggetto Animation. Il metodo e le sue opzioni temporali fanno parte della Web Animations API (WAAPI), non di ECMAScript 2024 né di altre edizioni di ECMAScript. La loro disponibilità dipende dall’ambiente di esecuzione.

In un array di fotogrammi chiave, ogni oggetto specifica i valori di proprietà CSS animabili, come opacity, in un punto dell’iterazione. offset colloca quel punto tra 0 e 1, estremi inclusi. I valori espliciti di offset devono essere in ordine non decrescente. Le posizioni omesse sono distribuite uniformemente: tre fotogrammi senza offset ricevono 0, 0.5 e 1. Un singolo oggetto con array di valori per proprietà, come { opacity: [0, 1] }, è un altro formato supportato.

Nelle opzioni un valore numerico di duration indica la durata di una sola iterazione in millisecondi. Passare un numero come secondo argomento è una scorciatoia per impostare soltanto duration. iterations indica il numero totale di iterazioni: il valore predefinito è 1, 2.5 significa due iterazioni complete e metà della terza, mentre il valore numerico Infinity non impone un limite finito. Con una durata positiva e finita e un numero finito di iterazioni, la durata attiva è duration * iterations, senza contare i ritardi.

Nelle opzioni, easing è una funzione di progressione CSS espressa come stringa e vale "linear" per impostazione predefinita. Cambia l’andamento dell’intera iterazione, non la durata. L’easing di un fotogramma chiave si applica da quel fotogramma al successivo; le due impostazioni possono combinarsi.

Esempi

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>WAAPI keyframes and timing</title>
<script>
  (() => {
    const element = document.createElement("div");
    const keyframes = [
      { opacity: 0 },
      { opacity: 1, easing: "ease-in" },
      { opacity: 0 },
    ];
    const animation = element.animate(keyframes, {
      duration: 600,
      easing: "ease-in-out",
      iterations: 2.5,
    });

    const effect = animation.effect;
    const { duration, easing, iterations, activeDuration } = effect.getComputedTiming();
    const offsets = effect.getKeyframes().map(frame => frame.computedOffset);
    console.log(`Offsets: ${offsets.join(", ")}`);
    console.log(`${duration} ms × ${iterations} = ${activeDuration} ms; easing: ${easing}`);
    animation.cancel();
  })();
</script>
</html>

Risultato

Offsets: 0, 0.5, 1
600 ms × 2.5 = 1500 ms; easing: ease-in-out

Salva l’esempio come file HTML, aprilo in un browser compatibile con WAAPI e controlla la console di sviluppo. L’elemento non viene inserito nella pagina: l’esempio stampa senza attese le posizioni e i valori temporali calcolati, poi annulla l’animazione.

Lezioni correlate

  • JavaScript · Lezione 29 · Intermedio · Versione: 3

Fonti