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

CKTIS / JavaScript

DOMTokenList: adicionar e remover tokens

Usa `add()` e `remove()` para alterar tokens específicos, como os nomes das classes de um elemento, sem substituir todo o atributo. Vê em que casos um token inválido faz falhar a chamada.

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

Sintaxe

tokenList.add(...tokens);
tokenList.remove(...tokens);

add() e remove() são métodos de instância de DOMTokenList, um conjunto ordenado de tokens únicos que distingue maiúsculas de minúsculas. element.classList devolve uma lista ligada ao atributo class: alterar a lista atualiza o atributo, e as alterações ao atributo são visíveis mesmo através de uma referência à lista guardada anteriormente. Outras propriedades, como HTMLLinkElement.relList, também devolvem uma DOMTokenList.

add() acrescenta no fim os tokens em falta, pela ordem dos argumentos e sem criar duplicados. remove() elimina os tokens correspondentes e ignora os tokens válidos que não estão presentes. Ambos os métodos aceitam zero ou mais tokens e devolvem undefined se a chamada for bem-sucedida. Sem argumentos, o conjunto de tokens não muda, mas a reescrita do atributo pode uniformizar o espaçamento e eliminar duplicados do seu texto.

Passa cada nome de classe como uma cadeia de caracteres separada: element.classList.add("a", "b"), e não element.classList.add("a b"). Usa o nome da classe ("a"), não um seletor CSS (".a"). Ambos os métodos validam todos os tokens antes de alterar a lista. Uma cadeia vazia ("") lança uma DOMException com o nome SyntaxError; um token com um carácter de espaço em branco ASCII, como um espaço ou uma tabulação, lança InvalidCharacterError. Em ambos os casos, nem sequer é aplicado um token válido que surja antes na mesma chamada.

element.classList.remove() remove tokens, não o próprio elemento. element.remove() separa o elemento do seu nó pai. DOMTokenList é uma interface DOM da plataforma web e não faz parte do ECMAScript 2024. Confirma que o ambiente de execução de destino disponibiliza as APIs DOM de que precisas.

Exemplos

{
  const card = typeof document === "undefined"
    ? createClassOnlyCard()
    : document.createElement("div");
  card.setAttribute("class", "card is-loading");
  const tokens = card.classList;

  tokens.add("is-active", "is-ready", "is-active");
  console.log(card.getAttribute("class"));

  tokens.remove("is-loading", "missing");
  console.log(card.getAttribute("class"));

  try {
    tokens.add("pending", "two words");
  } catch (error) {
    console.log(error.name);
  }

  try {
    tokens.remove("card", "");
  } catch (error) {
    console.log(error.name);
  }

  console.log(card.getAttribute("class"));

  // Without a DOM, model only the class attribute and the operations used here.
  function createClassOnlyCard() {
    let value = null;
    const asciiWhitespace = /[\t\n\f\r ]+/;

    function update(tokens, apply) {
      for (const token of tokens) {
        if (token === "") {
          throw new DOMException("A token must not be empty.", "SyntaxError");
        }
        if (asciiWhitespace.test(token)) {
          throw new DOMException("A token must not contain ASCII whitespace.", "InvalidCharacterError");
        }
      }

      const classes = new Set((value ?? "").split(asciiWhitespace).filter(Boolean));
      for (const token of tokens) apply(classes, token);
      if (value !== null || classes.size > 0) value = [...classes].join(" ");
    }

    return {
      setAttribute(name, text) {
        if (name === "class") value = String(text);
      },
      getAttribute(name) {
        return name === "class" ? value : null;
      },
      classList: {
        add(...tokens) {
          update(tokens, (classes, token) => classes.add(token));
        },
        remove(...tokens) {
          update(tokens, (classes, token) => classes.delete(token));
        },
      },
    };
  }
}

Resultado

card is-loading is-active is-ready
card is-active is-ready
InvalidCharacterError
SyntaxError
card is-active is-ready

Executa o código na consola do navegador para usar a propriedade nativa `classList`. O elemento não é inserido no documento. Em Node.js, o exemplo usa um modelo local do atributo `class` e das operações apresentadas em vez do DOM. A última linha mostra que, depois das duas chamadas falhadas, `pending` continua ausente e `card` continua presente.

Lições relacionadas

  • JavaScript · Lição 1 · Avançado · Versão: 4
  • JavaScript · Lição 2 · Avançado · Versão: 4
  • JavaScript · Lição 3 · Avançado · Versão: 4
  • JavaScript · Lição 4 · Avançado · Versão: 4
  • JavaScript · Lição 5 · Avançado · Versão: 4
  • JavaScript · Lição 6 · Avançado · Versão: 4
  • JavaScript · Lição 8 · Avançado · Versão: 4
  • JavaScript · Lição 12 · Avançado · Versão: 4
  • JavaScript · Lição 13 · Avançado · Versão: 4
  • JavaScript · Lição 16 · Avançado · Versão: 4
  • JavaScript · Lição 18 · Avançado · Versão: 4
  • JavaScript · Lição 19 · Avançado · Versão: 4
  • JavaScript · Lição 22 · Avançado · Versão: 4
  • JavaScript · Lição 23 · Avançado · Versão: 4
  • JavaScript · Lição 26 · Avançado · Versão: 4
  • JavaScript · Lição 28 · Avançado · Versão: 4
  • JavaScript · Lição 29 · Avançado · Versão: 4
  • JavaScript · Lição 32 · Avançado · Versão: 4
  • JavaScript · Lição 33 · Avançado · Versão: 4
  • JavaScript · Lição 36 · Avançado · Versão: 4
  • JavaScript · Lição 37 · Avançado · Versão: 4
  • JavaScript · Lição 39 · Avançado · Versão: 4
  • JavaScript · Lição 40 · Avançado · Versão: 4
  • JavaScript · Lição 41 · Avançado · Versão: 4
  • JavaScript · Lição 45 · Avançado · Versão: 4
  • JavaScript · Lição 27 · Intermédio · Versão: 3
  • JavaScript · Lição 28 · Intermédio · Versão: 3
  • JavaScript · Lição 29 · Intermédio · Versão: 3
  • JavaScript · Lição 30 · Intermédio · Versão: 3
  • JavaScript · Lição 35 · Intermédio · Versão: 3
  • JavaScript · Lição 38 · Intermédio · Versão: 3
  • JavaScript · Lição 39 · Intermédio · Versão: 3
  • JavaScript · Lição 41 · Intermédio · Versão: 3
  • JavaScript · Lição 42 · Intermédio · Versão: 3

Fontes