Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / HTML

oncuechange — gerir alterações nas deixas ativas de uma faixa de texto

O atributo oncuechange especifica o código a executar para eventos cuechange, quando as deixas temporizadas de uma faixa de texto ficam ativas ou deixam de estar. Os objetos TextTrack também disponibilizam uma propriedade JavaScript com o mesmo nome.

Versão: WHATWG HTML Living Standard; index snapshot date recorded separately

Sintaxe

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

oncuechange é um atributo global de tratamento do evento cuechange. O seu valor contém instruções JavaScript, não um URL de ficheiro. Um destino habitual é um elemento track dentro de video ou audio; a disponibilidade global não significa que o navegador gere este evento em todos os elementos.

O evento indica que uma ou mais deixas de uma faixa de texto ficaram ativas ou deixaram de estar. O navegador envia-o para o objeto TextTrack e para o elemento track correspondente, se existir. Não é uma notificação de que a transferência de um ficheiro de legendas terminou.

Num processador de eventos do elemento, leia this.track.activeCues para obter as deixas atualmente ativas; num processador TextTrack, use this.activeCues. Tenha em conta o valor null, especialmente quando mode é "disabled". O modo "hidden" permite acompanhar as deixas ativas sem apresentar legendas.

Atribuir uma função a oncuechange substitui o processador anterior dessa propriedade; addEventListener("cuechange", handler) regista processadores independentes. Uma política CSP pode bloquear código nos atributos. O exemplo envia deliberadamente um evento sintético: verifica o tratamento do atributo sem ficheiros multimédia, mas não ativa quaisquer deixas da faixa.

Exemplos

<!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

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes