CKTIS / JavaScript
HTMLMediaElement: czas, głośność i zdarzenia odtwarzania
HTMLMediaElement udostępnia wspólne API elementów audio i video. Pozwala odczytywać stan odtwarzania, zmieniać pozycję i wyciszenie oraz aktualizować interfejs na podstawie zdarzeń zamiast zakładać, że polecenie natychmiast się powiodło.
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.currentTime = seconds; media.volume = 0.5; media.muted = true; media.addEventListener("timeupdate", render);HTMLMediaElement jest wspólnym interfejsem elementów audio i video. To Web API określone przez HTML, a nie funkcja konkretnej edycji ECMAScript. Obecność Node 24 nie dowodzi jego obsługi w przeglądarce. Podstawowy interfejs jest szeroko dostępny, ale volume ma ograniczenia zgodności; sprawdzaj docelowe przeglądarki i urządzenia.
HTMLMediaElement.currentTime określa pozycję w sekundach. Gdy readyState ma wartość HAVE_NOTHING, jak w przypadku elementu bez źródła w przykładzie, przypisanie zapisuje domyślną pozycję rozpoczęcia odtwarzania zamiast inicjować przewijanie. W pozostałych stanach przypisanie żąda przewinięcia w granicach dostępnej osi czasu. HTMLMediaElement.duration jest tylko do odczytu: liczba sekund, NaN bez dostępnych danych albo Infinity przy nieokreślonej długości. Obliczaj procent postępu wyłącznie dla skończonego, dodatniego czasu trwania. HTMLMediaElement.volume przyjmuje zakres 0–1. HTMLMediaElement.muted niezależnie wycisza dźwięk bez zmiany zapisanej głośności.
Właściwości tylko do odczytu HTMLMediaElement.paused i HTMLMediaElement.ended oznaczają odpowiednio stan pauzy i zakończenie odtwarzania; nie są zamienne. paused === false nie gwarantuje postępu, np. podczas buforowania. HTMLMediaElement.error zawiera null albo obiekt MediaError. Zdarzenia play i pause informują o zmianach stanu, natomiast metody play() i pause() wydają polecenia. Obsłuż odrzucenie obietnicy z play(), np. gdy zasady autoplay blokują odtwarzanie.
loadedmetadata sygnalizuje wczytanie metadanych, durationchange zmianę długości, a emptied opróżnienie stanu zasobu — odśwież wtedy także interfejs. timeupdate służy do aktualizacji pozycji, lecz nie jest zegarem klatkowym: częstotliwość zależy od obciążenia. volumechange dotyczy zmian volume lub muted; ended sygnalizuje koniec odtwarzania. Zdarzenie error może sygnalizować nie tylko błąd ładowania zasobu, lecz także krytyczny błąd dekodowania po rozpoczęciu odtwarzania. Odczytuj bieżące właściwości w obsłudze zdarzeń.
Przykład tworzy element bez źródła, rejestruje zdarzenia i wypisuje początkowy stan. Nie odtwarza pliku ani nie sprawdza dekodowania. NaN jest celowo zapisane jako tekst, aby serializacja JSON zachowała to rozróżnienie.
Przykłady
const media = document.createElement("audio");
const events = [
"timeupdate", "loadedmetadata", "durationchange", "emptied",
"play", "pause", "volumechange", "ended", "error"
];
function snapshot() {
return JSON.stringify({
currentTime: media.currentTime,
duration: Number.isNaN(media.duration) ? "NaN" : String(media.duration),
volume: media.volume,
muted: media.muted,
paused: media.paused,
ended: media.ended,
error: media.error === null ? null : media.error.code
});
}
for (const type of events) {
media.addEventListener(type, () => console.log(type, snapshot()));
}
console.log(snapshot());Wynik
{"currentTime":0,"duration":"NaN","volume":1,"muted":false,"paused":true,"ended":false,"error":null}Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.
Źródła
- HTMLMediaElement - Web APIs | MDN
- HTMLMediaElement: currentTime property - Web APIs | MDN
- HTMLMediaElement: duration property - Web APIs | MDN
- HTMLMediaElement: volume property - Web APIs | MDN
- HTMLMediaElement: timeupdate event - Web APIs | MDN
- HTMLMediaElement: volumechange event - Web APIs | MDN
- HTMLMediaElement: paused property - Web APIs | MDN
- HTMLMediaElement: ended property - Web APIs | MDN
- HTMLMediaElement: error property - Web APIs | MDN
- HTMLMediaElement: play() method - Web APIs | MDN