Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

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

Źródła