Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / HTML

oncuechange — gérer les changements des repères actifs d’une piste de texte

L’attribut oncuechange indique le code à exécuter lors des événements cuechange, quand des repères temporisés d’une piste de texte deviennent actifs ou cessent de l’être. Une propriété JavaScript du même nom est également disponible sur les objets TextTrack.

Version : WHATWG HTML Living Standard; index snapshot date recorded separately

Syntaxe

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

oncuechange est un attribut global de gestionnaire d’événement pour cuechange. Sa valeur contient des instructions JavaScript, et non une URL de fichier. Une cible courante est un élément track à l’intérieur de video ou audio ; sa disponibilité globale ne signifie pas que le navigateur déclenche cet événement sur chaque élément.

L’événement indique qu’un ou plusieurs repères de piste de texte sont devenus actifs ou ont cessé de l’être. Le navigateur le distribue à l’objet TextTrack et à l’élément track correspondant, s’il existe. Il ne signale pas la fin du téléchargement d’un fichier de sous-titres.

Dans un gestionnaire d’élément, lisez this.track.activeCues pour obtenir les repères actuellement actifs ; dans un gestionnaire TextTrack, utilisez this.activeCues. Tenez compte de la valeur null, en particulier lorsque mode vaut "disabled". Le mode "hidden" permet de suivre les repères actifs sans afficher les sous-titres.

Affecter une fonction à oncuechange remplace le gestionnaire précédent de cette propriété ; addEventListener("cuechange", handler) enregistre des écouteurs indépendants. Une politique CSP peut bloquer le code placé dans les attributs. L’exemple distribue délibérément un événement synthétique : il vérifie le traitement de l’attribut sans fichier multimédia, mais n’active aucun repère de piste.

Exemples

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

Résultat

cuechange: captions

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources