База знанияИзпитен център
BGБългарски
Избери език13

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

Източници