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

CKTIS / JavaScript

DOMTokenList: verificar e alternar a presença de tokens

`contains()` verifica se um token está presente sem alterar a lista. `toggle()` alterna ou define a sua presença com `force` e indica se o token fica presente após a chamada.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

tokens.contains(token)
tokens.toggle(token)
tokens.toggle(token, force)

element.classList fornece uma DOMTokenList que reflete em cada momento o atributo class do elemento. Estes métodos pertencem à API do DOM, não ao ECMAScript 2024. O suporte depende do ambiente de execução. No navegador, o exemplo usa o DOM nativo; em Node.js, usa uma implementação simplificada para os tokens válidos do exemplo.

tokens.contains(token) devolve true se o token exato estiver presente e false caso contrário. Não altera a lista, distingue maiúsculas de minúsculas e não procura partes de uma cadeia. Devolve false para uma cadeia vazia ou que contenha um carácter de espaço em branco ASCII.

tokens.toggle(token) adiciona um token ausente ou remove um token presente. tokens.toggle(token, true) garante que fica presente; tokens.toggle(token, false) garante que fica ausente. O resultado indica se o token está presente após a chamada, não se a lista foi alterada. Para que uma classe dependa de uma condição booleana, usa tokens.toggle(token, condition). Passar undefined como force equivale a omitir o argumento: tokens.toggle(token, undefined) alterna a presença do token. Qualquer outro valor passado a force é convertido em booleano: a cadeia "false" torna-se true, não false.

toggle() aceita um token de cada vez. Uma cadeia vazia lança uma DOMException com o nome SyntaxError; um carácter de espaço em branco ASCII no token lança uma DOMException com o nome InvalidCharacterError, mesmo que force seja false. Passa o nome da classe sem o ponto do seletor: "active", não ".active".

Exemplos

{
  function createExampleElement(initialClass) {
    if (typeof document !== "undefined") {
      const element = document.createElement("div");
      element.className = initialClass;
      return element;
    }

    // Node.js has no browser DOM. This stand-in handles the valid tokens used below.
    const classes = new Set([initialClass]);
    return {
      get className() {
        return [...classes].join(" ");
      },
      classList: {
        contains(token) {
          return classes.has(token);
        },
        toggle(token, force) {
          const present = force === undefined ? !classes.has(token) : Boolean(force);
          if (present) classes.add(token);
          else classes.delete(token);
          return present;
        },
      },
    };
  }

  const element = createExampleElement("panel");
  const tokens = element.classList;

  console.log(tokens.contains("active"));
  console.log(tokens.toggle("active"));
  console.log(tokens.toggle("active"));
  console.log(tokens.toggle("active", true));
  console.log(tokens.toggle("active", true));
  console.log(tokens.toggle("active", false));
  console.log(element.className);
}

Resultado

false
true
false
true
true
false
panel

As duas chamadas sem `force` adicionam e depois removem `active`. Ambas as chamadas com `true` devolvem `true`, embora a segunda não altere nada. A chamada com `false` remove `active`, deixando apenas `panel`.

Lições relacionadas

  • JavaScript · Lição 31 · Intermédio · Versão: 3

Fontes