WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

HTMLMediaElement: `paused` und die Ereignisse `play`, `pause`, `ended` und `error`

Unterscheide den aktuellen Medienzustand von Ereignissen und vom Ergebnis eines `play()`-Aufrufs. Erkenne eine Pause, das natürliche Ende und einen Medienfehler.

Version: ECMAScript 2024 and the current web platform; runtime support varies

Syntax

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 ist die Schnittstelle der Webplattform für Audio- und Videoelemente und gehört nicht zu ECMAScript. Die schreibgeschützte boolesche Eigenschaft media.paused ist anfangs true. false bedeutet, dass das Element nicht im Pausenzustand ist, beweist aber nicht, dass die Wiedergabe voranschreitet: Das Element kann auf Daten warten.

play() versucht, die Wiedergabe zu starten oder fortzusetzen. Die Methode gibt ein Promise zurück, das bei erfolgreichem Start erfüllt und bei einem Fehlschlag abgelehnt wird, etwa mit NotAllowedError, wenn die Autoplay-Regeln den Aufruf blockieren. Beim Wechsel von paused von true auf false wird play zur späteren Auslösung eingeplant. Das ist nicht playing, das den Start oder die Fortsetzung nach dem Warten auf Daten meldet. pause() gibt undefined zurück und löst keinen erneuten Zustandswechsel aus, wenn das Element bereits pausiert ist. pause wird nach dem Wechsel in den Pausenzustand ausgelöst.

ended meldet das Ende der Wiedergabe, keine gewöhnliche Pause. Am natürlichen Ende der Vorwärtswiedergabe kann pause ohne Aufruf von pause() vor ended auftreten. Bei loop === true und nichtnegativem playbackRate wird ended nicht ausgelöst. Der boolesche Wert media.ended ist ein Zustand, kein Ereignis.

Registriere Listener für diese vier Ereignisse direkt am Element: Sie steigen im DOM nicht auf und sind nicht abbrechbar. Das Ereignis error meldet einen Ressourcenfehler, etwa beim Laden oder Dekodieren. Prüfe media.error: Der Wert ist ein MediaError mit code oder null, wenn kein Fehler erfasst ist. Behandle die Ablehnung von play() separat; eine Autoplay-Sperre allein ist kein Ressourcenfehler.

Beispiele

<!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>

Ergebnis

paused=true
play: paused=false
pause: paused=true
ended: ended=true
error: code=4

Speichere das Beispiel als `media-demo.html` und öffne die Datei im Browser. Öffne die Browserkonsole und klicke auf `Run media demo`. Die erwartete Folge setzt PCM-WAV-Unterstützung, erlaubte `data:`-Medien-URLs und eine ununterbrochene Wiedergabe voraus. Nach einer Sekunde Stille löst das natürliche Ende zuerst `pause` und dann `ended` aus. Erst danach setzt der Code eine absichtlich ungültige Quelle. Wird `play()` abgelehnt, prüfe den Fehlernamen, statt die vollständige Folge zu erwarten.

Zugehörige Lektionen

  • JavaScript · Lektion 34 · Fortgeschritten · Version: 4

Quellen