CKTIS / JavaScript
HTMLMediaElement: `paused` a události `play`, `pause`, `ended` a `error`
Rozlišujte aktuální stav přehrávání, události a výsledek volání `play()`. Naučte se odlišit pozastavení, přirozený konec přehrávání a chybu zdroje médií.
Verze: 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 je rozhraní webové platformy pro prvky zvuku a videa, nikoli součást ECMAScriptu. Logická vlastnost media.paused je jen pro čtení a zpočátku má hodnotu true. Hodnota false říká, že prvek není v pozastaveném stavu, ale nedokazuje, že přehrávání postupuje: prvek může čekat na data.
play() se pokusí spustit nebo obnovit přehrávání. Vrací příslib, který se splní při úspěšném zahájení přehrávání nebo se při neúspěchu zamítne, například s chybou NotAllowedError, pokud požadavek blokují pravidla automatického přehrávání. Při změně paused z true na false se do fronty zařadí událost play. Nejde o playing, která oznamuje spuštění nebo obnovení po čekání na data. pause() vrací undefined a nezpůsobí další změnu stavu, pokud je prvek už pozastavený. Událost pause nastane až po přechodu do tohoto stavu.
ended oznamuje konec přehrávání, nikoli běžné pozastavení. Při přirozeném konci přehrávání vpřed může pause předcházet události ended i bez volání pause(). Pokud platí loop === true a playbackRate je nezáporné, událost ended nenastane. Logická vlastnost media.ended vyjadřuje stav, není to událost.
Tyto čtyři události poslouchejte přímo na prvku: neprobublávají stromem DOM a nelze je zrušit. Událost error oznamuje chybu zdroje, například při načítání nebo dekódování. Zkontrolujte media.error: je to MediaError s vlastností code, nebo null, pokud není zaznamenána žádná chyba. Zamítnutí příslibu z play() ošetřete zvlášť; samotné blokování automatického přehrávání není chybou zdroje.
Příklady
<!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>Výsledek
paused=true play: paused=false pause: paused=true ended: ended=true error: code=4
Uložte příklad jako `media-demo.html` a otevřete ho v prohlížeči. Otevřete konzoli prohlížeče a klikněte na `Run media demo`. Očekávaná posloupnost předpokládá podporu PCM WAV, povolené adresy `data:` pro média a nepřerušené přehrávání. Po jedné sekundě ticha vyvolá přirozený konec událost `pause` před `ended`; teprve pak kód nastaví záměrně neplatný zdroj. Pokud se příslib z `play()` zamítne, zkontrolujte název chyby a neočekávejte celou posloupnost.
Související lekce
- JavaScript · Lekce 34 · Pokročilá · Verze: 4