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

CKTIS / HTML

controlslist — escolher os controlos multimédia nativos

O atributo controlslist indica ao navegador que opções deve omitir nos controlos nativos de áudio e vídeo. O seu equivalente em JavaScript, HTMLMediaElement.controlsList, expõe uma lista de tokens. O suporte depende do navegador.

Versão: WICG Controls List draft; index snapshot date recorded separately

Sintaxe

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

controlslist é um atributo dos elementos audio e video que contém tokens separados por espaços. Ajuda o navegador a escolher os seus próprios controlos multimédia. Não ativa esses controlos por si só: para isso existe o atributo separado controls. Também não controla os botões de um leitor implementado por quem criou a página.

O token nodownload pede a omissão da opção de transferência, nofullscreen da opção de ecrã inteiro e noremoteplayback da opção de reprodução num dispositivo remoto. É possível combinar estes tokens. São indicações para a interface, não uma proteção do conteúdo: ocultar a opção de transferência não impede que o ficheiro seja guardado.

HTMLMediaElement.controlsList é o equivalente em JavaScript do atributo e devolve uma DOMTokenList. O nome do atributo é controlslist, enquanto o nome da propriedade é controlsList. Os métodos add(), remove() e contains() permitem gerir os tokens; ao alterar a lista, o atributo é atualizado. A propriedade devolve um objeto cujo conteúdo pode ser modificado.

O suporte é limitado, por isso verifica se controlsList existe antes de usar a API e testa a interface nos navegadores de destino. Detetar a propriedade, por si só, não prova que todas as indicações alterem o aspeto dos controlos. O exemplo abaixo verifica a sincronização entre a lista e o atributo sem carregar multimédia.

Exemplos

(() => {
  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"));
})();

Resultado

nodownload nofullscreen
true

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