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

CKTIS / HTML

controlslist — choisir les commandes multimédias natives

L’attribut controlslist indique au navigateur quelles options omettre dans les commandes audio et vidéo natives. Son équivalent JavaScript, HTMLMediaElement.controlsList, expose une liste de jetons. La prise en charge dépend du navigateur.

Version : WICG Controls List draft; index snapshot date recorded separately

Syntaxe

controlslist="nodownload nofullscreen noremoteplayback"; media.controlsList.add("nodownload")

controlslist est un attribut des éléments audio et video qui contient des jetons séparés par des espaces. Il aide le navigateur à choisir ses propres commandes multimédias. Il n’active pas ces commandes à lui seul : c’est le rôle de l’attribut distinct controls. Il ne contrôle pas non plus les boutons d’un lecteur créé par l’auteur de la page.

Le jeton nodownload demande d’omettre l’option de téléchargement, nofullscreen l’option plein écran et noremoteplayback l’option de lecture sur un appareil distant. Ces jetons peuvent être combinés. Ce sont des indications pour l’interface, pas une protection du contenu : masquer l’option de téléchargement n’empêche pas d’enregistrer le fichier.

HTMLMediaElement.controlsList est l’équivalent JavaScript de l’attribut et renvoie une DOMTokenList. Le nom de l’attribut est controlslist, tandis que celui de la propriété est controlsList. Les méthodes add(), remove() et contains() permettent de gérer les jetons ; modifier la liste met à jour l’attribut. La propriété renvoie un objet dont le contenu peut être modifié.

La prise en charge est limitée : vérifiez donc la présence de controlsList avant d’utiliser l’API et testez l’interface dans les navigateurs visés. La seule détection de la propriété ne prouve pas que chaque indication modifiera l’apparence des commandes. L’exemple ci-dessous vérifie la synchronisation entre la liste et l’attribut sans charger de média.

Exemples

(() => {
  const video = document.createElement("video");
  video.controls = true;
  video.setAttribute("controlslist", "nodownload");

  if (!("controlsList" in video)) {
    console.log("controlsList: unsupported");
    return;
  }

  video.controlsList.add("nofullscreen");
  console.log(video.getAttribute("controlslist"));
  console.log(video.controlsList.contains("nodownload"));
})();

Résultat

nodownload nofullscreen
true

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