HTMLMediaElement: play() Methode

Syntax

play()

Parameter

Keine.

Rückgabewert

Ein Promise, das aufgelöst wird, wenn die Wiedergabe begonnen hat, oder zurückgewiesen wird, wenn die Wiedergabe aus irgendeinem Grund nicht gestartet werden kann.

Ausnahmen

Der Rejection-Handler des Versprechens wird mit einem DOMException-Objekt aufgerufen, das als einziger Eingabeparameter übergeben wird (im Gegensatz zu einer traditionellen Ausnahme, die ausgelöst wird). Mögliche Fehler sind:

NotAllowedError DOMException

Wird bereitgestellt, wenn der Benutzeragent (Browser) oder das Betriebssystem die Wiedergabe von Medien im aktuellen Kontext oder in der aktuellen Situation nicht zulassen. Der Browser kann beispielsweise verlangen, dass der Benutzer die Medienwiedergabe ausdrücklich durch Klicken auf eine "Wiedergabe"-Schaltfläche startet, etwa aufgrund einer Berechtigungsrichtlinie.

NotSupportedError DOMException

Wird bereitgestellt, wenn die Medienquelle (die möglicherweise als MediaStream, MediaSource, Blob oder File angegeben ist) kein unterstütztes Medienformat darstellt.

Andere Ausnahmen können gemeldet werden, abhängig von den Implementierungsdetails des Browsers, der Medienwiedergabefunktion und so weiter.

Verwendungshinweise

Obwohl der Begriff "Autoplay" normalerweise als Bezugnahme auf Seiten, die unmittelbar beim Laden mit der Wiedergabe von Medien beginnen, verstanden wird, gelten die Autoplay-Richtlinien der Webbrowser auch für die von Skripten initiierte Wiedergabe von Medien, einschließlich der Aufrufe von play().

Wenn der Benutzeragent so konfiguriert ist, dass er keine automatische oder von Skripten initiierte Wiedergabe von Medien zulässt, führt ein Aufruf von play() dazu, dass das zurückgegebene Versprechen sofort mit einem NotAllowedError zurückgewiesen wird. Websites sollten auf diese Situation vorbereitet sein. Beispielsweise sollte eine Website keine Benutzeroberfläche anzeigen, die davon ausgeht, dass die Wiedergabe automatisch begonnen hat, sondern stattdessen ihre Benutzeroberfläche basierend darauf aktualisieren, ob das zurückgegebene Versprechen erfüllt oder zurückgewiesen wird. Weitere Informationen finden Sie im Beispiel unten.

Für noch detailliertere Informationen über Autoplay und Autoplay-Blockierung lesen Sie unseren Artikel Autoplay-Leitfaden für Media- und Web-Audio-APIs.

Beispiele

Bestätigung der Wiedergabe und Umgang mit Zuständen

Dieses Beispiel zeigt, wie Sie bestätigen können, dass die Wiedergabe begonnen hat, und wie Sie blockierte automatische Wiedergabe elegant handhaben.

Wenn dieses Beispiel ausgeführt wird, beginnt es damit, Referenzen zum <video>-Element sowie zur <button>-Schaltfläche zu sammeln, die zum Umschalten der Wiedergabe verwendet wird. Anschließend wird ein Ereignishandler für das click-Ereignis auf der Umschalttaste eingerichtet und versucht automatisch mit der Wiedergabe zu beginnen, indem die async playVideo()-Funktion aufgerufen wird.

Eine Hilfsfunktion toggleButton() lässt uns definieren, was im Code passieren soll, wenn wir ihr einen booleschen Wert übergeben, der den Wiedergabestatus darstellt (z. B. toggleButton(true)). Wenn die Wiedergabe erfolgreich ist, ändern sich der Text der Schaltfläche und ihr aria-label zu "Pause". Wenn die Wiedergabe fehlschlägt, zeigen die Schaltfläche und das aria-label "Play" an. Dies stellt sicher, dass die playButton mit dem Wiedergabestatus übereinstimmt, indem auf die Auflösung oder Zurückweisung des von play() zurückgegebenen Promise geachtet wird:

<div class="video-box">
  <video
    id="video"
    width="480"
    loop
    src="/shared-assets/videos/flower.mp4"></video>
  <button type="button" id="play-button" aria-label="Play"></button>
</div>

let videoElem = document.getElementById("video");
let playButton = document.getElementById("play-button");

playButton.addEventListener("click", handlePlayButton);
playVideo();

function toggleButton(playing) {
  if (playing) {
    playButton.textContent = "Pause";
    playButton.setAttribute("aria-label", "Pause");
  } else {
    playButton.textContent = "Play";
    playButton.setAttribute("aria-label", "Play");
  }
}

async function playVideo() {
  try {
    await videoElem.play();
    toggleButton(true);
  } catch (err) {
    toggleButton(false);
  }
}

function handlePlayButton() {
  if (videoElem.paused) {
    playVideo();
  } else {
    videoElem.pause();
    toggleButton(false);
  }
}

.video-box {
  position: relative;
}

#video {
  border: 2px solid black;
}

#play-button {
  position: absolute;
  top: 10px;
  left: 10px;
  padding: 8px 12px;
  background-color: black;
  color: white;
  border: none;
  cursor: pointer;
}

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Technologien für Webmedien
• Lernen: HTML-Video und -Audio
• Autoplay-Leitfaden für Media- und Web-Audio-APIs
• Verwendung der Web-Audio-API