CKTIS / JavaScript
HTMLMediaElement.play() — asynchroniczne rozpoczynanie odtwarzania
Metoda play() żąda rozpoczęcia lub wznowienia odtwarzania dźwięku albo filmu. Zwraca Promise, dlatego interfejs powinien uwzględniać zarówno rozpoczęcie odtwarzania, jak i odrzucenie żądania.
Wersja: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Składnia
media.play() // Promise<undefined>; media is an HTMLAudioElement or HTMLVideoElementHTMLMediaElement.play() to metoda przeglądarkowego Web API dla elementów audio i video, a nie funkcja ECMAScript. Nie przyjmuje argumentów. Zwraca Promise, który przy powodzeniu zostaje spełniony wartością undefined, gdy odtwarzanie się rozpoczyna — nie dopiero po zakończeniu materiału.
Używaj await media.play() wewnątrz try...catch. Sam powrót z wywołania ani paused === false nie potwierdzają rozpoczęcia odtwarzania. Oczekiwanie może trwać podczas pobierania danych; stan interfejsu aktualizuj po rozstrzygnięciu obietnicy.
NotAllowedError oznacza brak zgody na odtwarzanie, na przykład z powodu polityki autoodtwarzania. Wywołuj metodę bezpośrednio w obsłudze kliknięcia, ale nadal obsługuj odmowę. NotSupportedError dotyczy nieobsługiwanego źródła. Przerwanie oczekującego żądania przez pause() lub ponowne ładowanie może spowodować AbortError.
Przykład celowo podaje tekst zamiast nagrania, aby pokazać obsługę odrzucenia bez zewnętrznego pliku. To nie jest demonstracja udanego odtwarzania. API należy do HTML Living Standard; wersja Node 24 w repozytorium nie potwierdza jego dostępności w przeglądarce.
Przykłady
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;
}
});Wynik
Rejected: NotSupportedError
Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.