Znalostní bázeCentrum zkoušek
CSČeština
Vybrat jazyk13

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