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

CKTIS / JavaScript

DOMTokenList — gerir tokens com classList

DOMTokenList representa um conjunto de tokens, como as classes de um elemento acessíveis através de classList. Aprende a adicionar, remover, alternar e verificar tokens sem processar manualmente o texto do atributo class.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

const tokens = element.classList;
tokens.add(token1, token2);
tokens.remove(token1, token2);
tokens.toggle(token);
tokens.toggle(token, force);
tokens.contains(token);

DOMTokenList representa um conjunto ordenado de tokens e distingue maiúsculas de minúsculas. No valor do atributo, só os caracteres de espaço em branco ASCII separam os tokens. Por exemplo, um espaço não separável (U+00A0) pode fazer parte de um único token de classe em vez de separar duas classes. Um exemplo comum é element.classList: um objeto vivo que reflete o atributo class. As alterações à lista atualizam o atributo, e as alterações ao atributo são visíveis através do mesmo objeto. Não é um array de JavaScript.

DOMTokenList.add, chamado como tokens.add("card", "active"), adiciona tokens individuais e ignora os que já estão presentes. DOMTokenList.remove, por exemplo tokens.remove("active", "missing"), remove os tokens indicados; a ausência de um token não provoca um erro. Ambos os métodos aceitam vários argumentos e devolvem undefined. Passa as classes separadamente: tokens.add("card", "active"), não tokens.add("card active"). Em add(), um token vazio provoca uma DOMException com o nome SyntaxError, enquanto um token que contenha espaços em branco ASCII provoca InvalidCharacterError.

DOMTokenList.contains, usado como tokens.contains("active"), devolve true ou false sem alterar a lista. DOMTokenList.toggle, usado como tokens.toggle("selected"), adiciona um token ausente ou remove um presente. O valor devolvido indica se o token está presente depois da operação, não se ocorreu uma alteração. A forma tokens.toggle("ready", force) com o valor booleano true garante a presença do token, enquanto false garante a sua ausência. Usa esta forma para sincronizar com um estado explícito em vez de alternar sem critério.

Esta é uma API do DOM, não uma funcionalidade de uma edição específica do ECMAScript. A MDN assinala que a interface e os quatro métodos aqui abordados estão amplamente disponíveis desde julho de 2015; em navegadores mais antigos, verifica o suporte das variantes de chamada específicas. A presença de Node 24 num repositório não comprova o suporte do DOM. O exemplo requer um navegador; não é necessário que o elemento esteja anexado ao documento.

Exemplos

{
  const element = document.createElement("div");
  const tokens = element.classList;

  tokens.add("card", "active", "card");
  console.log(tokens.contains("active"));

  tokens.remove("active", "missing");
  console.log(tokens.toggle("selected"));
  console.log(tokens.toggle("selected", false));

  tokens.toggle("ready", true);
  console.log(element.className);
}

Resultado

true
true
false
card ready

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