Web Animations API - Aprender JavaScript

A Web Animations API

A Web Animations API (WAAPI) permite criar e controlar animações diretamente a partir do JavaScript, sem nenhuma biblioteca externa. Ela executa as animações no compositor nativo do navegador — o mesmo mecanismo que alimenta as animações CSS — oferecendo movimentos suaves com aceleração de hardware, mas com o controle programático das animações JavaScript: é possível reproduzir, pausar, reverter, acelerar, avançar e encadear animações em tempo de execução.

Esta página aborda as duas peças necessárias: o método element.animate(), que inicia uma animação, e o objeto Animation que ele retorna, usado para controlar a reprodução e saber quando a animação termina.

`element.animate(keyframes, options)`

Toda animação WAAPI começa com uma única chamada:

const animation = element.animate(keyframes, options);

keyframes — os estados visuais pelos quais a animação passa. Dois formatos são aceitos:
- um array de objetos, onde cada objeto representa um quadro: [{ opacity: 0 }, { opacity: 1 }]
- um object de arrays, onde cada propriedade lista seus valores ao longo da linha do tempo: { opacity: [0, 1] }
options — um número (a duração em milissegundos) ou um objeto de temporização como { duration: 1000, easing: "ease-in-out", fill: "forwards" }.

A chamada retorna um objeto Animation e começa a reproduzir imediatamente. Os nomes das propriedades usam o formato CSS em camelCase (backgroundColor, não background-color).

Animação Básica com a Web Animations API

Criar uma animação básica com a Web Animations API envolve definir os keyframes da animação, especificar o elemento alvo e configurar as opções de animação. Veja um exemplo simplificado de animação da opacidade de um 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>

Experimente Você Mesmo »

Este exemplo demonstra como animar a opacidade de um elemento usando a Web Animations API. Um botão aciona a animação, que altera suavemente a opacidade do elemento de invisível (0) para totalmente visível (1). Após a conclusão da animação, uma mensagem é exibida ao usuário. Isso ilustra o controle básico de animação e o tratamento de eventos.

Opções de temporização

O segundo argumento de animate() controla como a animação é executada ao longo do tempo. As chaves mais úteis são:

Opção	O que faz
`duration`	Duração de uma iteração, em milissegundos (ou uma string de tempo CSS como `"1s"`).
`iterations`	Quantas vezes repetir. Use `Infinity` para repetir indefinidamente.
`easing`	A curva de aceleração: `"linear"`, `"ease"`, `"ease-in-out"` ou um `cubic-bezier(...)`.
`fill`	Qual estado manter fora do intervalo ativo. `"forwards"` mantém o último quadro; `"backwards"` aplica o primeiro quadro durante o `delay`; `"both"` faz os dois.
`delay`	Milissegundos de espera antes de iniciar.
`direction`	`"normal"`, `"reverse"` ou `"alternate"` (vai e volta a cada iteração).

Sem fill: "forwards", o elemento volta imediatamente aos seus estilos originais assim que a animação termina — uma fonte comum de confusão. Defina-o quando o quadro final deve permanecer aplicado.

O objeto `Animation`

element.animate() retorna uma instância de Animation. Esse é o identificador usado após o início da animação:

Membro	Finalidade
`play()`	Inicia ou retoma a reprodução.
`pause()`	Congela no ponto atual.
`reverse()`	Executa a partir do ponto atual de volta ao início.
`finish()`	Avança direto ao fim (ou ao início, se revertida).
`cancel()`	Para e remove todos os efeitos, limpando os estilos aplicados.
`finished`	Uma Promise que se resolve quando a animação conclui — ideal para encadeamento com `await`.
`playState`	`"running"`, `"paused"`, `"finished"` ou `"idle"`.
`playbackRate`	Multiplicador de velocidade; `2` é o dobro da velocidade, `-1` reproduz ao contrário.

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"

Como finished é uma Promise real, é possível usar await para executar código somente após o término do movimento, ou para encadear animações de forma limpa — como o próximo exemplo demonstra.

Animações Complexas e Sequências

Para animações mais complexas e sequências, você pode encadear várias animações usando promises e async/await. Veja um exemplo de encadeamento de animações:

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

Experimente Você Mesmo »

Neste exemplo, a primeira animação aumenta a opacidade do elemento e o amplia, e após a conclusão, a segunda animação faz o elemento desaparecer e diminuir. Uma mensagem de conclusão é exibida ao final, demonstrando como encadear animações sequencialmente.

Controlando e Gerenciando Animações

A Web Animations API também fornece métodos para controlar e gerenciar animações. Por exemplo, é possível pausar, retomar ou cancelar uma animação. Veja um exemplo de como pausar e retomar uma animação:

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

Experimente Você Mesmo »

Este exemplo mostra como alternar entre os estados de reprodução e pausa de uma animação com um clique. A animação inicial faz um elemento aparecer e desaparecer continuamente. Ao clicar em um botão, o usuário pode pausar a animação se ela estiver em execução, ou reproduzi-la se estiver pausada. Mensagens indicam o estado atual da animação, melhorando a interação e o controle do usuário sobre os estados de animação.

Web Animations API vs animações CSS

Ambas são executadas no mesmo compositor, portanto o desempenho é comparável. A diferença está no controle:

Opte pelas animações CSS quando o movimento é declarativo e estático — um efeito hover, um spinner de carregamento, uma transição de entrada que pode ser definida inteiramente em uma folha de estilos.
Opte pela Web Animations API quando a animação depende de dados em tempo de execução ou da entrada do usuário: valores de keyframe dinâmicos, pausar e retomar sob demanda, sequenciar várias animações ou reagir ao término de uma delas via a promise finished.

Um meio-termo conveniente é manter os estilos em classes — veja Estilos e classes — e usar a WAAPI apenas para as transições que precisam de controle por script.

Conclusão

A Web Animation API capacita desenvolvedores web a criar animações cativantes e interativas que melhoram a experiência do usuário em sites e aplicações web. Ao dominar essa API, você pode criar animações que vão desde transições simples até sequências complexas, adicionando uma dimensão dinâmica e envolvente aos seus designs web. Seja para animar interfaces de usuário, adicionar efeitos visuais ou criar elementos de narrativa interativa, a Web Animations API fornece as ferramentas necessárias para dar vida às suas ideias criativas na web.

Prática

Quais funcionalidades a JavaScript Animation API oferece?

Ela permite criar animações na web.Ela ajuda a resolver equações matemáticas.A API é usada para criar animações baseadas em JavaScript em HTML.Ela permite fazer chamadas telefônicas usando JavaScript.Ela suporta apenas animações baseadas em CSS.

A Web Animations API

element.animate(keyframes, options)

Animação Básica com a Web Animations API

Opções de temporização

O objeto Animation

Animações Complexas e Sequências

Controlando e Gerenciando Animações

Web Animations API vs animações CSS

Conclusão

Prática

`element.animate(keyframes, options)`

O objeto `Animation`