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 Methode play()
des HTMLMediaElement
versucht, die Wiedergabe der Medien zu starten. Sie gibt ein Promise
zurück, das aufgelöst wird, wenn die Wiedergabe erfolgreich gestartet wurde.
Wenn es aus irgendeinem Grund nicht möglich ist, die Wiedergabe zu starten, z. B. aufgrund von Berechtigungsproblemen, wird das Promise zurückgewiesen.
Syntax
play()
Parameter
Keine.
Rückgabewert
Ein Promise
, das aufgelöst wird, wenn die Wiedergabe gestartet wurde, oder zurückgewiesen wird, wenn die Wiedergabe aus irgendeinem Grund nicht gestartet werden kann.
Hinweis: Browser, die vor 2019 veröffentlicht wurden, geben möglicherweise keinen Wert aus play()
zurück.
Ausnahmen
Der Rejektions-Handler des Promises wird mit einem DOMException
-Objekt aufgerufen, das als einziger Eingabeparameter übergeben wird (im Gegensatz zu einer traditionellen Ausnahme, die geworfen wird). Mögliche Fehler sind:
NotAllowedError
DOMException
-
Wenn der User Agent (Browser) oder das Betriebssystem die Wiedergabe von Medien im aktuellen Kontext oder in der aktuellen Situation nicht zulässt. Der Browser kann erfordern, dass der Benutzer die Medienwiedergabe explizit durch Klicken auf eine "Play"-Schaltfläche startet, z. B. aufgrund einer Permissions Policy.
NotSupportedError
DOMException
-
Wenn die Medienquelle (die z. B. als
MediaStream
,MediaSource
,Blob
oderFile
angegeben sein kann) kein unterstütztes Medienformat darstellt.
Weitere Ausnahmen können je nach Detailimplementierung des Browsers, der Medienplayer-Implementierung usw. gemeldet werden.
Anwendungshinweise
Obwohl der Begriff "Autoplay" normalerweise als bezogen auf Seiten gedacht wird, die sofort nach dem Laden Medien abspielen, gelten die Autoplay-Richtlinien von Webbrowsern auch für alle skriptgesteuerten Medienwiedergaben, einschließlich Aufrufen von play()
.
Wenn der User Agent so konfiguriert ist, dass er automatische oder skriptgesteuerte Medienwiedergaben nicht zulässt, führt das Aufrufen von play()
dazu, dass das zurückgegebene Promise sofort mit einem NotAllowedError
abgelehnt wird. Websites sollten darauf vorbereitet sein, diese Bedingungen zu handhaben. Beispielsweise sollte eine Seite keine Benutzeroberfläche präsentieren, die davon ausgeht, dass die Wiedergabe automatisch gestartet wurde, sondern sollte stattdessen ihre UI basierend darauf aktualisieren, ob das zurückgegebene Promise erfüllt oder abgelehnt wurde. Siehe das Beispiel unten für weitere Informationen.
Hinweis: Die play()
-Methode kann dazu führen, dass der Benutzer aufgefordert wird, die Erlaubnis zur Wiedergabe der Medien zu erteilen, 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.
Für noch detailliertere Informationen über Autoplay und Autoplay-Blockierung, lesen Sie unseren Artikel Autoplay-Leitfaden für Medien und Web Audio APIs.
Beispiele
Dieses Beispiel zeigt, wie bestätigt wird, dass die Wiedergabe begonnen hat und wie blockierte automatische Wiedergabe elegant gehandhabt wird:
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 durch die async
playVideo()
-Funktion 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 fehlschlägt, wird die Klasse des playButton
-Elements gelöscht, um sein Standardaussehen wiederherzustellen. Dies stellt sicher, dass die Wiedergabeschaltfläche dem tatsächlichen Wiedergabestatus entspricht, indem die Auflösung oder Zurückweisung 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 Wiedergabeumschaltfläche eingerichtet und versucht, die Wiedergabe automatisch durch Aufrufen 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