CKTIS / JavaScript
HTMLMediaElement: čas, hlasitost a události přehrávání
HTMLMediaElement poskytuje společné API pro zvukové a obrazové prvky. Umožňuje číst stav přehrávání, měnit pozici a ztlumení a aktualizovat rozhraní podle událostí, místo abyste předpokládali, že příkaz k přehrávání uspěl okamžitě.
Verze: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntaxe
media.currentTime = seconds; media.volume = 0.5; media.muted = true; media.addEventListener("timeupdate", render);HTMLMediaElement je společné rozhraní pro zvukové a obrazové prvky. Jde o webové API definované HTML, nikoli o funkci konkrétní verze ECMAScriptu. Přítomnost Node 24 nedokládá podporu v prohlížeči. Základní rozhraní je široce dostupné, ale volume má omezení kompatibility; ověřte cílové prohlížeče a zařízení.
HTMLMediaElement.currentTime udává pozici v sekundách. Pokud má readyState hodnotu HAVE_NOTHING, jako u prvku bez zdroje v příkladu, přiřazením se uloží výchozí pozice pro zahájení přehrávání, aniž by se spustil přesun. V ostatních stavech přiřazení vyžádá přesun v rámci dostupné časové osy. HTMLMediaElement.duration je pouze pro čtení: počet sekund, NaN, pokud nejsou dostupná data, nebo Infinity při neurčité délce. Procento průběhu počítejte jen při konečné kladné délce. HTMLMediaElement.volume přijímá hodnoty od 0 do 1. HTMLMediaElement.muted nezávisle ztlumí zvuk, aniž změní uloženou hlasitost.
Vlastnosti pouze pro čtení HTMLMediaElement.paused a HTMLMediaElement.ended označují stav pozastavení, respektive dokončení přehrávání; nelze je zaměňovat. paused === false nezaručuje, že přehrávání postupuje, například během načítání do vyrovnávací paměti. HTMLMediaElement.error obsahuje null nebo objekt MediaError. Události play a pause oznamují změny stavu, zatímco metody play() a pause() vydávají příkazy. Ošetřete zamítnutí promise z play(), například když zásady automatického přehrávání přehrávání zablokují.
loadedmetadata signalizuje načtení metadat, durationchange změnu délky a emptied vyprázdnění stavu zdroje — tehdy také aktualizujte rozhraní. Událost timeupdate používejte k aktualizaci pozice, nikoli jako hodinový signál pro snímky: její četnost závisí na zatížení. volumechange se týká změn volume nebo muted; ended signalizuje konec přehrávání. Událost error může signalizovat nejen chybu při načítání zdroje, ale i fatální chybu dekódování po zahájení přehrávání. V obslužných funkcích událostí čtěte aktuální vlastnosti.
Příklad vytvoří prvek bez zdroje, zaregistruje události a vypíše počáteční stav. Nepřehrává soubor ani netestuje dekódování. NaN je záměrně převedeno na text, aby serializace JSON tento rozdíl zachovala.
Příklady
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());Výsledek
{"currentTime":0,"duration":"NaN","volume":1,"muted":false,"paused":true,"ended":false,"error":null}Zobrazený kód a uvedený výsledek byly ověřeny v izolovaném prostředí metodou zaznamenanou v dokladu o ověření této přesné verze.
Zdroje
- 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