CKTIS / JavaScript
HTMLMediaElement: stan `paused` oraz zdarzenia `play`, `pause`, `ended` i `error`
Odróżnij bieżący stan odtwarzacza od zdarzeń oraz od wyniku wywołania `play()`. Naucz się rozpoznawać pauzę, naturalny koniec odtwarzania i błąd zasobu.
Wersja: ECMAScript 2024 and the current web platform; runtime support varies
Składnia
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 to interfejs platformy WWW dla elementów audio i wideo, a nie część ECMAScript. Właściwość media.paused jest wartością logiczną tylko do odczytu i początkowo wynosi true. Wartość false oznacza, że element nie jest w stanie pauzy, lecz nie dowodzi, że odtwarzanie rzeczywiście postępuje: element może czekać na dane.
play() próbuje rozpocząć lub wznowić odtwarzanie. Zwraca obietnicę, która spełnia się po pomyślnym rozpoczęciu odtwarzania, a w razie niepowodzenia zostaje odrzucona, np. z NotAllowedError, gdy zasady autoodtwarzania blokują żądanie. Zdarzenie play jest kolejkowane przy zmianie paused z true na false; nie jest to playing, które sygnalizuje rozpoczęcie lub wznowienie odtwarzania po oczekiwaniu na dane. pause() zwraca undefined i nie powoduje kolejnej zmiany stanu, jeśli element już jest w pauzie. Zdarzenie pause jest dostarczane po zmianie stanu na pauzę.
ended sygnalizuje koniec odtwarzania, nie zwykłą pauzę. Przy naturalnym końcu odtwarzania w przód pause może poprzedzać ended bez wywołania pause(); przy loop === true i nieujemnym playbackRate zdarzenie ended nie występuje. Właściwość logiczna media.ended to stan, a nie zdarzenie.
Nasłuchuj tych czterech zdarzeń bezpośrednio na elemencie: nie propagują się w górę drzewa DOM i nie można ich anulować. Zdarzenie error sygnalizuje awarię zasobu, np. przy ładowaniu lub dekodowaniu. Sprawdź media.error: to MediaError z właściwością code albo null, gdy nie odnotowano błędu. Niezależnie obsłuż odrzucenie obietnicy z play(); sama blokada autoodtwarzania nie oznacza błędu zasobu.
Przykłady
<!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>Wynik
paused=true play: paused=false pause: paused=true ended: ended=true error: code=4
Zapisz przykład jako `media-demo.html` i otwórz go w przeglądarce. Otwórz konsolę przeglądarki i kliknij `Run media demo`. Sekwencja zakłada obsługę PCM WAV, zezwolenie na adresy `data:` dla multimediów i odtwarzanie bez przerwy. Po sekundzie ciszy naturalny koniec wywołuje `pause` przed `ended`; dopiero potem kod podstawia celowo nieprawidłowe źródło. Jeśli `play()` zostanie odrzucone, sprawdź nazwę błędu zamiast oczekiwać pełnej sekwencji.
Powiązane lekcje
- JavaScript · Lekcja 34 · Zaawansowany · Wersja: 4