Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Animation.play(): iniciar e retomar animações

Animation.play() inicia ou retoma uma animação existente. Não cria outra animação nem devolve uma promessa.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

animation.play()

animation.play() não recebe argumentos e devolve undefined. Numa animação que usa a linha temporal do documento (document.timeline), como no exemplo, play() mantém a posição atual se a velocidade efetiva de reprodução for positiva e o tempo atual não for negativo nem tiver atingido o fim do efeito. A essa velocidade, se o tempo atual atingir ou ultrapassar o fim do efeito, play() faz a animação voltar ao início, mesmo que esteja em pausa.

Após uma chamada a updatePlaybackRate(), a velocidade efetiva de reprodução usada por play() pode diferir de playbackRate: se houver uma alteração de velocidade pendente, play() usa o valor pendente. Na linha temporal do documento, um valor negativo pendente pode, portanto, fazer com que play() salte do tempo zero para o fim de um efeito de duração finita, mesmo que playbackRate ainda indique um valor positivo.

O início da reprodução pode aguardar uma tarefa assíncrona. animation.ready indica que está pronta, enquanto animation.finished indica que terminou. A chamada a play() não aguarda por nenhuma delas.

Esta é uma API Web, não uma funcionalidade ECMAScript. Verifique o suporte no navegador de destino; o Node 24 não o comprova. O exemplo mostra como a animação é retomada a partir de uma posição dentro do intervalo temporal do efeito, e não o caso de uma velocidade negativa pendente. Utiliza um efeito sem elemento de destino e não desenha nada.

Exemplos

const effect = new KeyframeEffect(null, [], { duration: 1000 });
const animation = new Animation(effect, document.timeline);

animation.currentTime = 400;
const result = animation.play();
console.log(result === undefined, animation.currentTime);

animation.finish();
console.log(animation.playState, animation.currentTime);

Resultado

true 400
finished 1000

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes