CKTIS / JavaScript
Zdarzenia elementu HTMLMediaElement
Obsługuj dziewięć zdarzeń audio i wideo, aby aktualizować pozycję, czas trwania i stan odtwarzacza oraz wykrywać reset, koniec odtwarzania i błędy.
Wersja: ECMAScript 2024 and the current web platform; runtime support varies
Składnia
media.addEventListener(type, (event) => { /* read event.currentTarget here */ });
// type: "timeupdate" | "loadedmetadata" | "durationchange" | "emptied"
// | "play" | "pause" | "volumechange" | "ended" | "error"HTMLMediaElement to interfejs przeglądarkowy wspólny dla elementów audio i video, a nie część ECMAScript. Zarejestruj nasłuchiwacze przez addEventListener() bezpośrednio na elemencie, najlepiej przed ustawieniem src: te zdarzenia nie propagują się w górę drzewa i nie można ich anulować. W procedurze obsługi odczytuj aktualny stan elementu, zamiast odtwarzać go z kolejności zdarzeń.
loadedmetadata oznacza, że dostępne są metadane, np. wymiary wideo, ale nie gwarantuje gotowości do odtwarzania. durationchange sygnalizuje ustalenie lub zmianę czasu trwania; duration podaje sekundy, NaN, gdy brak danych, lub Infinity, gdy koniec nie jest określony. emptied oznacza wyzerowanie stanu zasobu, np. przy ponownym ładowaniu. Wyczyść wtedy dane poprzedniego materiału w interfejsie: sam reset nie musi wywołać durationchange.
Przy timeupdate odczytaj currentTime w sekundach, aby odświeżyć wskaźnik pozycji. Zdarzenie występuje m.in. podczas odtwarzania i przewijania; nie jest zegarem o stałej częstotliwości ani sygnałem każdej klatki. play oznacza przejście paused na false, a nie faktyczny start (playing). pause sygnalizuje przejście do stanu wstrzymania, nie chwilowy brak danych. Przy volumechange sprawdź zarówno volume, jak i muted: wystarczy zmiana jednej z tych wartości.
ended sygnalizuje dotarcie do końca, nie zwykłą pauzę, choć na końcu może wystąpić również pause. Przy loop ustawionym na true i nieujemnym playbackRate zdarzenie ended nie występuje. Przy error sprawdź media.error, np. media.error?.code; MediaError dotyczy zasobu. Oddzielnie obsłuż odrzucenie obietnicy play(): np. NotAllowedError może wynikać z zasad autoodtwarzania i nie musi wywołać zdarzenia error.
Przykłady
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>HTMLMediaElement events</title>
</head>
<body>
<script>
(() => {
const panel = document.createElement('div');
const audio = document.createElement('audio');
audio.controls = true;
audio.preload = 'metadata';
panel.append(audio);
// Generate three seconds of silence as mono, 8-bit PCM WAV.
const rate = 8000;
const samples = 3 * rate;
const bytes = new Uint8Array(44 + samples);
const view = new DataView(bytes.buffer);
const tag = (offset, text) => bytes.set(new TextEncoder().encode(text), offset);
const u16 = (offset, value) => view.setUint16(offset, value, true);
const u32 = (offset, value) => view.setUint32(offset, value, true);
tag(0, 'RIFF'); u32(4, 36 + samples); tag(8, 'WAVE');
tag(12, 'fmt '); u32(16, 16); u16(20, 1); u16(22, 1);
u32(24, rate); u32(28, rate); u16(32, 1); u16(34, 8);
tag(36, 'data'); u32(40, samples); bytes.fill(128, 44);
const wav = URL.createObjectURL(new Blob([bytes], { type: 'audio/wav' }));
const bad = URL.createObjectURL(new Blob(['not audio'], { type: 'audio/wav' }));
const listeners = new AbortController();
const types = ['timeupdate', 'loadedmetadata', 'durationchange', 'emptied',
'play', 'pause', 'volumechange', 'ended', 'error'];
for (const type of types) {
audio.addEventListener(type, ({ currentTarget: media }) => {
console.log(type, {
currentTime: media.currentTime, duration: media.duration,
paused: media.paused, ended: media.ended,
volume: media.volume, muted: media.muted,
errorCode: media.error?.code ?? null
});
}, { signal: listeners.signal });
}
function button(label, action) {
const control = document.createElement('button');
control.type = 'button';
control.textContent = label;
control.addEventListener('click', action);
panel.append(control);
}
button('Mute / unmute', () => { audio.muted = !audio.muted; });
button('Reload', () => { audio.src = wav; });
button('Load invalid audio', () => { audio.src = bad; });
button('Remove demo', () => {
listeners.abort();
audio.removeAttribute('src');
audio.load();
panel.remove();
URL.revokeObjectURL(wav);
URL.revokeObjectURL(bad);
});
document.body.prepend(panel);
audio.src = wav;
})();
</script>
</body>
</html>Wynik
Expected observations, not a fixed transcript (each event name is logged with a state object): - Initial load: durationchange and loadedmetadata; duration is 3 seconds at loadedmetadata. - Play, pause, resume, and let the clip finish: play, timeupdate (repeated), pause, play again, and eventually ended. A pause event can also occur at the end. - Mute / unmute: volumechange; muted toggles. - Reload after metadata is available: emptied, then fresh durationchange and loadedmetadata. - Load invalid audio: error with a non-null errorCode; emptied can appear first.
Zapisz przykład jako plik HTML i otwórz go w przeglądarce obsługującej PCM WAV i zezwalającej na multimedia z adresów `blob:`. Zdarzenia sprawdzaj w konsoli deweloperskiej. Użyj wbudowanych kontrolek do odtwarzania i pauzy. Przykład generuje trzy sekundy ciszy bez pobierania pliku; czasy i liczba wpisów mogą się różnić. `Remove demo` usuwa kontrolki i zwalnia adresy obiektowe.
Powiązane lekcje
- JavaScript · Lekcja 28 · Średniozaawansowany · Wersja: 3