CKTIS / JavaScript
Eventi di HTMLMediaElement
Usa nove eventi audio e video per sincronizzare posizione, durata e controlli e rilevare un ripristino della risorsa, la fine della riproduzione o un errore.
Versione: ECMAScript 2024 and the current web platform; runtime support varies
Sintassi
media.addEventListener(type, (event) => { /* read event.currentTarget here */ });
// type: "timeupdate" | "loadedmetadata" | "durationchange" | "emptied"
// | "play" | "pause" | "volumechange" | "ended" | "error"HTMLMediaElement è l’interfaccia del browser comune agli elementi audio e video, non una parte di ECMAScript. Usa addEventListener() direttamente sull’elemento multimediale, preferibilmente prima di impostare src: questi eventi non risalgono agli antenati e non sono annullabili. In ogni gestore leggi lo stato attuale dell’elemento invece di ricostruirlo dall’ordine degli eventi.
loadedmetadata indica che sono disponibili metadati come le dimensioni del video, non che tutto sia pronto per la riproduzione. durationchange segnala una durata appena determinata o aggiornata: duration è espressa in secondi, vale NaN quando mancano i dati e Infinity se non c’è una fine determinata. emptied indica che lo stato della risorsa è stato azzerato, ad esempio durante un nuovo caricamento. Rimuovi dall’interfaccia i dati della risorsa precedente: il solo azzeramento non deve necessariamente generare durationchange.
Con timeupdate, leggi currentTime in secondi per aggiornare l’indicatore di posizione. L’evento può verificarsi durante la riproduzione o durante uno spostamento sulla traccia; non è un timer a frequenza fissa né un segnale per ogni fotogramma. play indica che paused è passato a false, non che la riproduzione è iniziata (playing). pause segnala il passaggio allo stato di pausa, non una temporanea mancanza di dati. Con volumechange, leggi sia volume sia muted: una variazione dell’uno o dell’altro può generarlo.
ended segnala il raggiungimento della fine, non una normale pausa, anche se alla fine può verificarsi anche pause. Se loop è true e playbackRate non è negativo, ended non viene generato. Con error, esamina media.error, ad esempio media.error?.code: questo MediaError riguarda la risorsa multimediale. Gestisci separatamente i rifiuti della promessa di play(): per esempio, NotAllowedError può dipendere dalle regole di riproduzione automatica senza generare un evento multimediale error.
Esempi
<!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>Risultato
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.
Salva l’esempio come file HTML e aprilo in un browser che supporta WAV PCM e consente risorse multimediali `blob:`. Consulta gli eventi nella console di sviluppo. Usa i controlli integrati per avviare e mettere in pausa la riproduzione. La demo genera tre secondi di silenzio senza scaricare file; tempi e numero degli eventi possono variare. `Remove demo` rimuove i controlli e libera gli URL di oggetto.
Lezioni correlate
- JavaScript · Lezione 28 · Intermedio · Versione: 3