CKTIS / JavaScript
HTMLMediaElement : `paused` et les événements `play`, `pause`, `ended` et `error`
Distinguez l’état courant du média, les événements et le résultat d’un appel à `play()`. Reconnaissez une pause, une fin naturelle et une défaillance de la ressource.
Version : ECMAScript 2024 and the current web platform; runtime support varies
Syntaxe
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 est l’interface de la plateforme web pour les éléments audio et vidéo ; elle ne fait pas partie d’ECMAScript. La propriété booléenne media.paused, en lecture seule, vaut initialement true. La valeur false indique que l’élément n’est pas en pause, mais ne garantit pas que la lecture avance : l’élément peut attendre des données.
play() tente de démarrer ou de reprendre la lecture. La méthode renvoie une promesse qui est tenue lorsque la lecture a bien démarré et rejetée en cas d’échec, par exemple avec NotAllowedError si les règles de lecture automatique bloquent la demande. L’événement play est mis en file d’attente quand paused passe de true à false. Il ne s’agit pas de playing, qui signale le démarrage ou la reprise après une attente de données. pause() renvoie undefined et ne change pas de nouveau l’état si l’élément est déjà en pause. L’événement pause est émis après le passage à l’état de pause.
ended signale la fin de la lecture, pas une simple pause. À la fin naturelle d’une lecture vers l’avant, pause peut précéder ended sans appel à pause() ; ended n’est pas émis si loop === true et que playbackRate est positif ou nul. Le booléen media.ended représente un état, pas un événement.
Écoutez ces quatre événements directement sur l’élément : ils ne remontent pas dans le DOM et ne sont pas annulables. L’événement error signale une défaillance de la ressource, par exemple au chargement ou au décodage. Consultez media.error : il s’agit d’un MediaError doté d’un code, ou de null si aucune erreur n’est enregistrée. Gérez séparément le rejet de play() : un blocage de la lecture automatique n’est pas en soi une défaillance de la ressource.
Exemples
<!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>Résultat
paused=true play: paused=false pause: paused=true ended: ended=true error: code=4
Enregistrez l’exemple sous `media-demo.html` et ouvrez-le dans un navigateur. Ouvrez la console du navigateur et cliquez sur `Run media demo`. La séquence attendue suppose la prise en charge du WAV PCM, l’autorisation des URL `data:` pour les médias et une lecture sans interruption. Après une seconde de silence, la fin naturelle déclenche `pause` avant `ended` ; ensuite seulement, le code définit une source volontairement invalide. Si `play()` est rejetée, examinez le nom de l’erreur plutôt que d’attendre la séquence complète.
Leçons associées
- JavaScript · Leçon 34 · Avancé · Version : 4