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 HTMLMediaElement play()-Methode versucht, die Wiedergabe der Medien 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. Berechtigungsproblemen, 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 aus irgendeinem Grund die Wiedergabe nicht gestartet werden kann.

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

Ausnahmen

Der Ablehnungs-Handler des Promises 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 das Abspielen von Medien 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 "Play"-Schaltfläche startet, beispielsweise aufgrund einer Permissions Policy.

NotSupportedError DOMException

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

Weitere Ausnahmen können gemeldet werden, abhängig von den Browser-Implementierungsdetails, der Medienplayer-Implementierung und so weiter.

Anwendungshinweise

Obwohl der Begriff "Autoplay" normalerweise auf Seiten bezogen wird, die zu Ladenbeginn direkt mit der Medienwiedergabe beginnen, gelten die Autoplay-Richtlinien der Webbrowser auch für jede skriptinitiierte Wiedergabe von Medien, einschließlich Aufrufen von play().

Wenn der Benutzeragent so konfiguriert ist, dass automatische oder skriptinitiierte Medienwiedergabe nicht erlaubt ist, führt der Aufruf von play() dazu, dass das zurückgegebene Promise sofort mit einem NotAllowedError abgelehnt wird. Webseiten sollten auf diese Situation vorbereitet sein. Beispielsweise sollte eine Seite keine Benutzeroberfläche darstellen, die davon ausgeht, dass die Wiedergabe automatisch begonnen hat, sondern stattdessen die Benutzeroberfläche basierend darauf aktualisieren, ob das zurückgegebene Promise erfüllt oder abgelehnt wird. Weitere Informationen finden Sie im Beispiel unten.

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

Für noch tiefere Informationen über Autoplay und die Blockierung von Autoplay, lesen Sie unseren Artikel Autoplay Leitfaden für Medien und Web-Audio-APIs.

Beispiele

Dieses Beispiel zeigt, wie man bestätigt, dass die Wiedergabe begonnen hat und wie man blockierte automatische Wiedergabe elegant handhabt:

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 des Videos mit der asynchronen async Funktion playVideo() ein- und ausgeschaltet. Es versucht, das Video abzuspielen, und setzt bei Erfolg den Klassennamen des playButton-Elements auf "playing". Falls die Wiedergabe nicht gestartet werden kann, wird die Klasse des playButton-Elements gelöscht, wodurch sein Standardaussehen wiederhergestellt wird. Dies stellt sicher, dass die Wiedergabeschaltfläche den tatsächlichen Wiedergabestatus widerspiegelt, indem die Erfüllung oder Ablehnung des von play() zurückgegebenen Promise beobachtet wird.

Wenn dieses Beispiel ausgeführt wird, beginnt es damit, Referenzen zu dem <video>-Element sowie zu dem <button> zu sammeln, das zum Umschalten der Wiedergabe verwendet wird. Anschließend wird ein Ereignishandler für das click-Ereignis auf der Wiedergabe-Umschaltfläche eingerichtet und es wird versucht, die Wiedergabe automatisch durch Aufruf von playVideo() zu starten.

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

Spezifikationen

Specification
HTML
# dom-media-play-dev

Browser-Kompatibilität

Siehe auch