Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

DOMTokenList : ajouter et supprimer des jetons

Utilisez `add()` et `remove()` pour modifier des jetons, comme les classes d’un élément, sans remplacer tout l’attribut. Voyez dans quels cas un jeton invalide fait échouer l’appel.

Version : ECMAScript 2024 and the current web platform; runtime support varies

Syntaxe

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

add() et remove() sont des méthodes d’instance de DOMTokenList, un ensemble ordonné de jetons uniques qui distingue les majuscules des minuscules. element.classList donne accès à une liste liée à l’attribut class : modifier la liste met à jour l’attribut, et modifier l’attribut se répercute sur la liste, même via une référence obtenue auparavant. D’autres propriétés, comme HTMLLinkElement.relList, renvoient aussi une DOMTokenList.

add() ajoute à la fin les jetons absents, dans l’ordre des arguments et sans créer de doublons. remove() retire les jetons correspondants et ignore les jetons valides qui sont absents. Les deux méthodes acceptent zéro ou plusieurs jetons et renvoient undefined en cas de réussite. Sans argument, les jetons présents restent les mêmes, mais la réécriture de l’attribut peut uniformiser l’espacement et supprimer les doublons de son texte.

Passez chaque nom de classe dans une chaîne distincte : element.classList.add("a", "b"), et non element.classList.add("a b"). Utilisez le nom de classe ("a"), pas un sélecteur CSS (".a"). Les deux méthodes vérifient tous les jetons avant de modifier la liste. Une chaîne vide ("") déclenche une DOMException nommée SyntaxError ; un jeton contenant un caractère d’espacement ASCII, comme une espace ou une tabulation, déclenche InvalidCharacterError. Dans les deux cas, même un jeton valide passé plus tôt dans le même appel n’est pas appliqué.

element.classList.remove() retire des jetons, pas l’élément lui-même. element.remove() détache l’élément de son parent. DOMTokenList est une interface DOM de la plateforme web, et non une partie d’ECMAScript 2024. Vérifiez que votre environnement cible fournit les API DOM nécessaires.

Exemples

{
  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));
        },
      },
    };
  }
}

Résultat

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

Exécutez le code dans la console d’un navigateur pour utiliser la propriété native `classList`. L’élément n’est pas inséré dans le document. Dans Node.js, l’exemple utilise un modèle local de l’attribut `class` et des opérations présentées, à la place du DOM. La dernière ligne montre qu’après les deux échecs, `pending` est toujours absent et `card` est toujours présent.

Leçons associées

  • JavaScript · Leçon 1 · Avancé · Version : 4
  • JavaScript · Leçon 2 · Avancé · Version : 4
  • JavaScript · Leçon 3 · Avancé · Version : 4
  • JavaScript · Leçon 4 · Avancé · Version : 4
  • JavaScript · Leçon 5 · Avancé · Version : 4
  • JavaScript · Leçon 6 · Avancé · Version : 4
  • JavaScript · Leçon 8 · Avancé · Version : 4
  • JavaScript · Leçon 12 · Avancé · Version : 4
  • JavaScript · Leçon 13 · Avancé · Version : 4
  • JavaScript · Leçon 16 · Avancé · Version : 4
  • JavaScript · Leçon 18 · Avancé · Version : 4
  • JavaScript · Leçon 19 · Avancé · Version : 4
  • JavaScript · Leçon 22 · Avancé · Version : 4
  • JavaScript · Leçon 23 · Avancé · Version : 4
  • JavaScript · Leçon 26 · Avancé · Version : 4
  • JavaScript · Leçon 28 · Avancé · Version : 4
  • JavaScript · Leçon 29 · Avancé · Version : 4
  • JavaScript · Leçon 32 · Avancé · Version : 4
  • JavaScript · Leçon 33 · Avancé · Version : 4
  • JavaScript · Leçon 36 · Avancé · Version : 4
  • JavaScript · Leçon 37 · Avancé · Version : 4
  • JavaScript · Leçon 39 · Avancé · Version : 4
  • JavaScript · Leçon 40 · Avancé · Version : 4
  • JavaScript · Leçon 41 · Avancé · Version : 4
  • JavaScript · Leçon 45 · Avancé · Version : 4
  • JavaScript · Leçon 27 · Intermédiaire · Version : 3
  • JavaScript · Leçon 28 · Intermédiaire · Version : 3
  • JavaScript · Leçon 29 · Intermédiaire · Version : 3
  • JavaScript · Leçon 30 · Intermédiaire · Version : 3
  • JavaScript · Leçon 35 · Intermédiaire · Version : 3
  • JavaScript · Leçon 38 · Intermédiaire · Version : 3
  • JavaScript · Leçon 39 · Intermédiaire · Version : 3
  • JavaScript · Leçon 41 · Intermédiaire · Version : 3
  • JavaScript · Leçon 42 · Intermédiaire · Version : 3

Sources