CKTIS / JavaScript
HTMLMediaElement: `paused` e gli eventi `play`, `pause`, `ended` ed `error`
Distingui lo stato attuale del contenuto multimediale dagli eventi e dall’esito di `play()`. Impara a riconoscere una pausa, la fine naturale e un errore della risorsa.
Versione: ECMAScript 2024 and the current web platform; runtime support varies
Sintassi
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 è l’interfaccia della piattaforma web per gli elementi audio e video; non fa parte di ECMAScript. La proprietà booleana media.paused, di sola lettura, vale inizialmente true. Il valore false indica che l’elemento non è in pausa, ma non garantisce che la riproduzione avanzi: l’elemento potrebbe essere in attesa di dati.
play() tenta di avviare o riprendere la riproduzione. Restituisce una promessa che viene risolta quando la riproduzione inizia correttamente o rifiutata in caso di errore, per esempio con NotAllowedError se le regole di riproduzione automatica bloccano la richiesta. L’evento play viene accodato quando paused passa da true a false. È distinto da playing, che segnala l’avvio o la ripresa dopo un’attesa di dati. pause() restituisce undefined e non provoca un’altra transizione se l’elemento è già in pausa. L’evento pause viene emesso dopo il passaggio allo stato di pausa.
ended segnala la fine della riproduzione, non una normale pausa. Alla fine naturale della riproduzione in avanti, pause può precedere ended anche senza una chiamata a pause(); ended non viene emesso se loop === true e playbackRate è non negativo. Il booleano media.ended indica uno stato, non un evento.
Ascolta questi quattro eventi direttamente sull’elemento: non risalgono il DOM e non sono annullabili. L’evento error segnala un problema con la risorsa, per esempio durante il caricamento o la decodifica. Controlla media.error: è un MediaError con code, oppure null se non risulta alcun errore. Gestisci separatamente il rifiuto di play(): il blocco della riproduzione automatica non è di per sé un errore della risorsa.
Esempi
<!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>Risultato
paused=true play: paused=false pause: paused=true ended: ended=true error: code=4
Salva l’esempio come `media-demo.html` e aprilo in un browser. Apri la console del browser e fai clic su `Run media demo`. La sequenza prevista presuppone il supporto per WAV PCM, l’autorizzazione a caricare contenuti multimediali da URL `data:` e la riproduzione senza interruzioni. Dopo un secondo di silenzio, la fine naturale produce `pause` prima di `ended`; solo allora il codice assegna una sorgente volutamente non valida. Se `play()` viene rifiutata, controlla il nome dell’errore invece di aspettarti l’intera sequenza.
Lezioni correlate
- JavaScript · Lezione 34 · Avanzato · Versione: 4