A API Web Animations (WAAPI) permite que você crie e controle animações diretamente dentro do JavaScript. Com WAAPI, você pode trabalhar com animações de forma mais dinâmica, facilitando a manipulação delas. Vamos dar uma olhada no WAAPI com mais detalhes, para que você possa começar a trabalhar com animações diretamente dentro do seu código JavaScript. No núcleo do WAAPI está o construtor Animation, que fornece vários métodos e propriedades de instância que permitem animar elementos dinamicamente. Um método significativo no construtor Animation é animate(). Ele permite que você crie uma animação especificando keyframes e opções como duração, direção, easing e iterações. Aqui está a sintaxe básica do método animate():

element.animate(keyframes, options);

Dê uma olhada no exemplo.

<link rel="stylesheet" href="styles.css" />
<div class="square" id="square"></div>
<script src="index.js"></script>

body {
  background: #f1f1f1;
  display: flex;
  align-items: center;
  justify-content: center;
  height: 100vh;
}

.square {
  background: #1b1b32;
  width: 10rem;
  aspect-ratio: 1/1;
}

const square = document.querySelector("#square");

const animation = square.animate(
  [{ transform: "translateX(0px)" }, { transform: "translateX(100px)" }],
  {
    duration: 2000, // makes animation lasts 2 seconds
    iterations: Infinity, // loops indefinitely
    direction: "alternate", // moves back and forth
    easing: "ease-in-out" // smooth easing
  }
);

O resultado no navegador será um quadrado azul se movendo para frente e para trás horizontalmente. Os métodos de instância do construtor Animation incluem:

play()
pause()
reverse()
finish()
cancel()

E as propriedades da instância incluem:

playbackRate
currentTime
startTime
effect
timeline
playState
finished
onfinish
oncancel

Vamos modificar o exemplo para usar os métodos play(), pause() e a propriedade onfinish. Aqui está a nova versão:

<link rel="stylesheet" href="styles.css" />
<div class="square" id="square"></div>

<button id="playBtn">Play</button>
<button id="pauseBtn">Pause</button>
<script src="index.js"></script>

body {
  background: #f1f1f1;
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  height: 100vh;
}
.square {
  background: #1b1b32;
  width: 10rem;
  aspect-ratio: 1/1;
  margin-bottom: 20px;
}
button {
  margin: 10px;
  padding: 10px 20px;
  font-size: 16px;
}

const square = document.querySelector("#square");
const playBtn = document.querySelector("#playBtn");
const pauseBtn = document.querySelector("#pauseBtn");

const animation = square.animate(
  [{ transform: "translateX(0px)" }, { transform: "translateX(200px)" }],
  {
    duration: 5000, // Animation lasts 5 seconds
    // iterations: Infinity, // Loops indefinitely
    direction: "alternate", // Moves back and forth
    easing: "ease-in-out" // Smooth easing function
  }
);

// Set the onfinish property to log a message when the animation ends
animation.onfinish = () => {
  console.log("Animation finished!");
};

// Play the animation when the "Play" button is clicked
playBtn.addEventListener("click", () => {
  animation.play();
  console.log("You start the animation");
});

// Pause the animation when the "Pause" button is clicked
pauseBtn.addEventListener("click", () => {
  animation.pause();
  console.log("You pause the animation");
});

O resultado no navegador mostrará a caixa azul se movendo da esquerda para a direita quando o botão play for clicado. WAAPI amplia as capacidades das animações CSS ao fornecer um controle mais dinâmico sobre as animações diretamente dentro do JavaScript. Com animações CSS, você define animações de forma declarativa usando propriedades como animation-name, animation-duration e animation-timing-function. Você também tem a oportunidade de fazer a mesma coisa usando o método animate() do WAAPI. A diferença é que você pode controlar as animações que cria com o método animate() de forma mais direta e dinâmica, mas com animações CSS, você precisa fazer muito mais definindo estilos personalizados e acionando-os dentro do seu arquivo JavaScript. Animação CSS é ideal para animações simples e declarativas que são executadas automaticamente. Isso inclui efeitos de hover, transições ou animações que não precisam de muita interação depois de acionadas. Se a sua animação precisa responder a interações do usuário como cliques e rolagens ou você quer que o usuário possa pausar, reverter ou alterar a velocidade dinamicamente, WAAPI é a melhor escolha.  Você pode considerar combinar as animações WAAPI e CSS quando quiser a simplicidade do CSS para uma configuração básica mas precisar controlar as animações em tempo de execução.