Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / HTML

oncuechange — gestionar cambios en las señales activas de una pista de texto

El atributo oncuechange especifica el código que se ejecuta ante eventos cuechange cuando las señales temporizadas de una pista de texto pasan a estar activas o dejan de estarlo. Los objetos TextTrack también disponen de una propiedad JavaScript con el mismo nombre.

Versión: WHATWG HTML Living Standard; index snapshot date recorded separately

Sintaxis

oncuechange="JavaScript statements"
trackElement.oncuechange = handler;
textTrack.oncuechange = handler;

oncuechange es un atributo global de gestión de eventos para cuechange. Su valor contiene instrucciones JavaScript, no una URL de archivo. Un destino habitual es un elemento track dentro de video o audio; que el atributo esté disponible globalmente no significa que el navegador genere este evento en todos los elementos.

El evento indica que una o más señales de una pista de texto han pasado a estar activas o han dejado de estarlo. El navegador lo envía al objeto TextTrack y al elemento track correspondiente, si existe. No es una notificación de que haya terminado la descarga de un archivo de subtítulos.

En un controlador de elemento, lee this.track.activeCues para obtener las señales activas en ese momento; en un controlador TextTrack, usa this.activeCues. Ten en cuenta el valor null, especialmente cuando mode es "disabled". El modo "hidden" permite seguir las señales activas sin mostrar los subtítulos.

Asignar una función a oncuechange sustituye el controlador anterior de esa propiedad; addEventListener("cuechange", handler) registra controladores independientes. Una política CSP puede bloquear el código basado en atributos. El ejemplo envía deliberadamente un evento sintético: comprueba el funcionamiento del atributo sin archivos multimedia, pero no activa ninguna señal de pista.

Ejemplos

<!doctype html>
<meta charset="utf-8">
<title>oncuechange</title>
<video>
  <track id="captions" kind="captions" srclang="en" src="data:text/vtt,WEBVTT%0A%0A"
    oncuechange="document.getElementById('result').textContent = event.type + ': ' + this.kind">
</video>
<output id="result"></output>
<script>
  const trackElement = document.getElementById('captions');
  trackElement.dispatchEvent(new Event('cuechange'));
</script>

Resultado

cuechange: captions

El código mostrado y el resultado declarado se verificaron en un entorno aislado mediante el método registrado en la evidencia de verificación de esta versión exacta.

Fuentes