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

CKTIS / JavaScript

DOMTokenList: adicionar, remover e alternar tokens

Altera tokens individuais com `add()`, `remove()` e `toggle()`. Usa o argumento `force` quando uma condição deve determinar se um token está presente.

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

Sintaxe

list.add(...tokens)
list.remove(...tokens)
list.toggle(token)
list.toggle(token, force)

element.classList disponibiliza uma DOMTokenList: um conjunto dinâmico de tokens únicos que distingue maiúsculas de minúsculas. Alterar a lista atualiza o atributo class e as alterações ao atributo são visíveis mesmo através de uma referência à lista guardada anteriormente. Estes métodos pertencem à API do DOM, não ao ECMAScript; o ambiente de execução tem de disponibilizar as APIs do DOM necessárias.

add() adiciona os tokens indicados sem criar duplicados. remove() remove os tokens indicados e ignora os que não estão presentes. Ambos os métodos aceitam vários tokens como argumentos separados e devolvem undefined.

toggle(token) inverte o estado de um único token: adiciona-o se estiver ausente ou remove-o se estiver presente. Em toggle(token, force), true garante a presença e false garante a ausência. Ambas as formas devolvem um valor booleano que indica se o token está presente após a chamada, não se houve alguma alteração. Usa toggle(token, condicao) para fazer depender a presença do token de uma condição booleana.

Nos três métodos, um token vazio lança uma DOMException com o nome SyntaxError; um token que contenha um caráter de espaço em branco ASCII lança uma DOMException com o nome InvalidCharacterError. Usa list.add("a", "b"), não list.add("a b"): os argumentos não são divididos em tokens.

Exemplos

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

    // Without a DOM, model only the operations used here with valid tokens.
    const tokens = new Set();
    return {
      classList: {
        add(...values) {
          for (const value of values) tokens.add(value);
        },
        remove(...values) {
          for (const value of values) tokens.delete(value);
        },
        toggle(value, force = !tokens.has(value)) {
          if (force) tokens.add(value);
          else tokens.delete(value);
          return tokens.has(value);
        }
      },
      getAttribute(name) {
        return name === "class" ? [...tokens].join(" ") : null;
      }
    };
  }

  const element = createExampleElement();
  const list = element.classList;

  list.add("card", "pending", "card");
  list.remove("pending", "missing");

  console.log(list.toggle("active"));
  console.log(list.toggle("active"));
  console.log(list.toggle("ready", true));
  console.log(list.toggle("active", false));
  console.log(element.getAttribute("class"));
}

Resultado

true
false
true
false
card ready

Executa o código na consola do navegador. O elemento não é inserido na página. Os dois primeiros resultados mostram a adição e a remoção de `active`. Os dois seguintes mostram que `ready` está presente e que `active` continua ausente. A última linha contém o valor do atributo `class`.

Lições relacionadas

  • JavaScript · Lição 7 · Avançado · Versão: 4
  • JavaScript · Lição 32 · Intermédio · Versão: 3
  • JavaScript · Lição 34 · Intermédio · Versão: 3
  • JavaScript · Lição 43 · Intermédio · Versão: 3

Fontes