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.