HTMLMediaElement: play()-Methode

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Die play()-Methode des HTMLMediaElement versucht, die Wiedergabe des Mediums zu starten. Sie gibt ein Promise zurück, das aufgelöst wird, wenn die Wiedergabe erfolgreich gestartet wurde.

Wenn die Wiedergabe aus irgendeinem Grund, wie z.B. Berechtigungsprobleme, nicht gestartet werden kann, wird das Promise abgelehnt.

Syntax

js
play()

Parameter

Keine.

Rückgabewert

Ein Promise, das aufgelöst wird, wenn die Wiedergabe gestartet wurde, oder abgelehnt wird, falls die Wiedergabe aus irgendeinem Grund nicht gestartet werden kann.

Hinweis: Browser, die vor 2019 veröffentlicht wurden, geben möglicherweise keinen Wert von play() zurück.

Ausnahmen

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

NotAllowedError DOMException

Wird angegeben, wenn der User Agent (Browser) oder das Betriebssystem die Wiedergabe des Mediums im aktuellen Kontext oder in der aktuellen Situation nicht zulässt. Der Browser kann verlangen, dass der Benutzer die Medienwiedergabe explizit durch Klicken auf eine „Wiedergabe“-Schaltfläche startet, beispielsweise aufgrund einer Berechtigungsrichtlinie.

NotSupportedError DOMException

Wird angegeben, wenn die Medienquelle (die als MediaStream, MediaSource, Blob oder File angegeben sein kann) kein unterstütztes Medienformat darstellt.

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

Verwendungshinweise

Obwohl der Begriff "Autoplay" normalerweise mit Seiten verbunden ist, die bei Ladevorgang sofort mit der Wiedergabe von Medien beginnen, gelten die Autoplay-Richtlinien der Webbrowser auch für jegliche skriptinitiierte Wiedergabe von Medien, einschließlich Aufrufen von play().

Wenn der User Agent so konfiguriert ist, dass er keine automatische oder skriptinitiierte Wiedergabe von Medien zulässt, führt ein Aufruf von play() dazu, dass das zurückgegebene Promise sofort mit einem NotAllowedError abgelehnt wird. Websites sollten auf diese Situation vorbereitet sein. Beispielsweise sollte eine Website keine Benutzeroberfläche präsentieren, die annimmt, dass die Wiedergabe automatisch begonnen hat, sondern stattdessen die Benutzeroberfläche basierend darauf aktualisieren, ob das zurückgegebene Promise erfüllt oder abgelehnt wurde. Siehe das untenstehende Beispiel für weitere Informationen.

Hinweis: Die play()-Methode kann dazu führen, dass der Benutzer um Erlaubnis gebeten wird, das Medium abzuspielen, was zu einer möglichen Verzögerung führen kann, bevor das zurückgegebene Promise aufgelöst wird. Stellen Sie sicher, dass Ihr Code keine sofortige Antwort erwartet.

Weitere ausführliche Informationen zum Thema Autoplay und Blockierung von Autoplay finden Sie in unserem Artikel Autoplay-Leitfaden für Medien- und Web-Audio-APIs.

Beispiele

Dieses Beispiel zeigt, wie bestätigt werden kann, dass die Wiedergabe gestartet wurde, und wie blockierte automatische Wiedergabe elegant verarbeitet werden kann:

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

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

async function playVideo() {
  try {
    await videoElem.play();
    playButton.classList.add("playing");
  } catch (err) {
    playButton.classList.remove("playing");
  }
}

function handlePlayButton() {
  if (videoElem.paused) {
    playVideo();
  } else {
    videoElem.pause();
    playButton.classList.remove("playing");
  }
}

In diesem Beispiel wird die Wiedergabe eines Videos durch die async-Funktion playVideo() ein- und ausgeschaltet. Sie versucht, das Video abzuspielen, und wenn dies erfolgreich ist, wird der Klassenname des playButton-Elements auf "playing" gesetzt. Wenn die Wiedergabe nicht gestartet werden kann, wird die Klasse des playButton-Elements gelöscht, wodurch sein Standardaussehen wiederhergestellt wird. Dies stellt sicher, dass die Wiedergabetaste dem tatsächlichen Zustand der Wiedergabe entspricht, indem sie auf die Auflösung oder Ablehnung des durch play() zurückgegebenen Promise achtet.

Wenn dieses Beispiel ausgeführt wird, beginnt es damit, Referenzen auf das <video>-Element sowie auf das <button>, das verwendet wird, um die Wiedergabe ein- und auszuschalten, zu sammeln. Es wird dann ein Ereignishandler für das click-Ereignis auf den Wiedergabeumschaltknopf eingerichtet und versucht, die Wiedergabe automatisch durch einen Aufruf von playVideo() zu starten.

Sie können dieses Beispiel in Echtzeit auf Glitch ausprobieren oder remixen.

Spezifikationen

Specification
HTML Standard
# dom-media-play-dev

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch