Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

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 HTMLVideoElement

HTMLMediaElement.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.

Źródła