CKTIS / JavaScript
HTMLMediaElement: `paused` e os eventos `play`, `pause`, `ended` e `error`
Distingue o estado atual do elemento multimédia dos eventos e do resultado de chamar `play()`. Aprende a reconhecer uma pausa, o fim natural e uma falha do recurso.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
media.paused
media.ended
media.error
media.play() // Promise<void>
media.pause() // undefined
media.addEventListener("play", listener)
media.addEventListener("pause", listener)
media.addEventListener("ended", listener)
media.addEventListener("error", listener)HTMLMediaElement é a interface da plataforma Web para elementos de áudio e vídeo; não faz parte de ECMAScript. A propriedade booleana media.paused é só de leitura e começa com o valor true. O valor false indica que o elemento não está em pausa, mas não garante que a reprodução esteja a avançar: o elemento pode estar à espera de dados.
play() tenta iniciar ou retomar a reprodução. Devolve uma promessa que é cumprida quando a reprodução começa com êxito ou rejeitada se falhar, por exemplo com NotAllowedError se a política de reprodução automática bloquear o pedido. O evento play é colocado em fila quando paused passa de true para false. É distinto de playing, que assinala o início ou a retoma após a espera por dados. pause() devolve undefined e não provoca outra transição se o elemento já estiver em pausa. O evento pause é emitido após a entrada no estado de pausa.
ended assinala o fim da reprodução, não uma pausa normal. No fim natural da reprodução para a frente, pause pode anteceder ended sem uma chamada a pause(); ended não é emitido quando loop === true e playbackRate não é negativo. O booleano media.ended representa um estado, não um evento.
Escuta estes quatro eventos diretamente no elemento: não sobem na árvore do DOM e não são canceláveis. O evento error assinala uma falha do recurso, por exemplo ao carregar ou descodificar. Consulta media.error: é um MediaError com code, ou null quando não há nenhum erro registado. Trata a rejeição de play() separadamente: o bloqueio da reprodução automática, por si só, não é uma falha do recurso.
Exemplos
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Media playback events</title>
</head>
<body>
<audio id="media"></audio>
<button id="start" type="button">Run media demo</button>
<script>
(() => {
// Build one second of silent, unsigned 8-bit mono PCM WAV.
const rate = 8000;
const wav = new Uint8Array(44 + rate);
const view = new DataView(wav.buffer);
const text = (offset, value) => {
for (let i = 0; i < value.length; i++) wav[offset + i] = value.charCodeAt(i);
};
text(0, "RIFF");
view.setUint32(4, wav.length - 8, true);
text(8, "WAVEfmt ");
view.setUint32(16, 16, true);
view.setUint16(20, 1, true);
view.setUint16(22, 1, true);
view.setUint32(24, rate, true);
view.setUint32(28, rate, true);
view.setUint16(32, 1, true);
view.setUint16(34, 8, true);
text(36, "data");
view.setUint32(40, rate, true);
wav.fill(128, 44);
const media = document.getElementById("media");
const start = document.getElementById("start");
media.addEventListener("play", () => console.log(`play: paused=${media.paused}`));
media.addEventListener("pause", () => console.log(`pause: paused=${media.paused}`));
media.addEventListener("ended", () => {
console.log(`ended: ended=${media.ended}`);
media.src = "data:text/plain,not-a-media-file";
}, { once: true });
media.addEventListener("error", () => console.log(`error: code=${media.error?.code}`));
start.addEventListener("click", async () => {
start.remove();
console.log(`paused=${media.paused}`);
media.src = `data:audio/wav;base64,${btoa(String.fromCharCode(...wav))}`;
try {
await media.play();
} catch (error) {
console.log(`play() rejected: ${error.name}`);
}
}, { once: true });
})();
</script>
</body>
</html>Resultado
paused=true play: paused=false pause: paused=true ended: ended=true error: code=4
Guarda o exemplo como `media-demo.html` e abre-o num navegador. Abre a consola do navegador e clica em `Run media demo`. A sequência esperada pressupõe suporte para WAV PCM, permissão para carregar multimédia com URL `data:` e reprodução sem interrupções. Após um segundo de silêncio, o fim natural produz `pause` antes de `ended`; só depois o código atribui uma fonte deliberadamente inválida. Se `play()` for rejeitada, verifica o nome do erro em vez de esperares a sequência completa.
Lições relacionadas
- JavaScript · Lição 34 · Avançado · Versão: 4