CKTIS / JavaScript
HTMLMediaElement: `paused` и събитията `play`, `pause`, `ended` и `error`
Разграничавай текущото състояние на възпроизвеждането от събитията и резултата от `play()`. Разпознавай пауза, естествен край и грешка в медийния ресурс.
Версия: ECMAScript 2024 and the current web platform; runtime support varies
Синтаксис
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 е интерфейсът на уеб платформата за аудио- и видеоелементи и не е част от ECMAScript. Булевото свойство media.paused е само за четене и първоначално е true. Стойност false означава, че елементът не е в пауза, но не доказва, че възпроизвеждането напредва: елементът може да изчаква данни.
play() се опитва да започне или възобнови възпроизвеждането. Методът връща промис, който се изпълнява при успешно начало и се отхвърля при неуспех, например с NotAllowedError, ако правилата за автоматично възпроизвеждане блокират заявката. Събитието play се поставя в опашка, когато paused се промени от true на false. То е различно от playing, което сигнализира начало или възобновяване след изчакване на данни. pause() връща undefined и не предизвиква нов преход, ако елементът вече е в пауза. Събитието pause се изпраща след преминаването в това състояние.
ended сигнализира край на възпроизвеждането, а не обикновена пауза. При естествен край на възпроизвеждане напред pause може да предхожда ended без извикване на pause(); ended не се задейства, ако loop === true и playbackRate е неотрицателна стойност. Булевото media.ended е състояние, а не събитие.
Слушай за тези четири събития директно на елемента: те не се разпространяват нагоре в DOM и не могат да бъдат отменени. Събитието error сигнализира за проблем с ресурса, например при зареждане или декодиране. Провери media.error: стойността е MediaError със свойство code или null, ако няма отчетена грешка. Обработвай отхвърлянето на промиса от play() отделно: блокирането на автоматичното възпроизвеждане само по себе си не е грешка в ресурса.
Примери
<!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>Резултат
paused=true play: paused=false pause: paused=true ended: ended=true error: code=4
Запази примера като `media-demo.html` и го отвори в браузър. Отвори конзолата на браузъра и натисни `Run media demo`. Очакваната последователност предполага поддръжка на PCM WAV, разрешение за зареждане на медия от URL адреси с `data:` и възпроизвеждане без прекъсване. След една секунда тишина естественият край предизвиква `pause` преди `ended`; чак след това кодът задава умишлено невалиден източник. Ако промисът от `play()` бъде отхвърлен, провери името на грешката, вместо да очакваш цялата последователност.
Свързани уроци
- JavaScript · Урок 34 · Напреднало · Версия: 4