CKTIS / JavaScript
HTMLMediaElement.play() — Wiedergabe asynchron starten
Die Methode play() fordert an, die Audio- oder Videowiedergabe zu starten oder fortzusetzen. Sie gibt ein Promise zurück. Die Benutzeroberfläche sollte daher sowohl den Wiedergabestart als auch eine Ablehnung der Anfrage berücksichtigen.
Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntax
media.play() // Promise<undefined>; media is an HTMLAudioElement or HTMLVideoElementHTMLMediaElement.play() ist eine Web-API-Methode des Browsers für audio- und video-Elemente, keine ECMAScript-Funktion. Sie akzeptiert keine Argumente. Sie gibt ein Promise zurück, das mit undefined erfüllt wird, sobald die Wiedergabe beginnt – nicht erst, wenn die Medienwiedergabe beendet ist.
Verwende await media.play() innerhalb von try...catch. Weder die Rückkehr des Aufrufs noch paused === false bestätigen, dass die Wiedergabe begonnen hat. Während Daten geladen werden, kann das Promise noch ausstehen. Aktualisiere die Benutzeroberfläche, nachdem es abgeschlossen ist.
NotAllowedError bedeutet, dass die Wiedergabe nicht erlaubt ist, zum Beispiel aufgrund einer Autoplay-Richtlinie. Rufe die Methode direkt in einem Klick-Handler auf, behandle eine Ablehnung aber trotzdem. NotSupportedError betrifft eine nicht unterstützte Quelle. Wird eine ausstehende Anfrage durch pause() oder erneutes Laden unterbrochen, kann AbortError auftreten.
Das Beispiel verwendet absichtlich Text statt einer Aufnahme, um die Behandlung einer Ablehnung ohne externe Datei zu zeigen. Es demonstriert keine erfolgreiche Wiedergabe. Diese API gehört zum HTML Living Standard; Node 24 in einem Repository belegt nicht ihre Verfügbarkeit im Browser.
Beispiele
const media = document.createElement('audio');
media.src = 'data:text/plain,not-media';
const button = document.createElement('button');
button.textContent = 'Test play()';
const status = document.createElement('pre');
document.body.append(button, status);
button.addEventListener('click', async () => {
button.disabled = true;
try {
await media.play();
status.textContent = 'Playback started';
} catch (error) {
status.textContent = `Rejected: ${error.name}`;
} finally {
button.disabled = false;
}
});Ergebnis
Rejected: NotSupportedError
Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.