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

CKTIS / JavaScript

Options de MutationObserver : types de mutations, sous-arbre, filtre et anciennes valeurs

Configurez `observe()` pour suivre les changements de nœuds enfants, d’attributs ou de données de caractères, et choisissez la portée de l’observation et les anciennes valeurs à conserver.

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

Syntaxe

const observer = new MutationObserver((records, observer) => {
  for (const record of records) {
    // Read record.type, record.target, or record.oldValue.
  }
});

observer.observe(target, {
  childList: true,
  attributes: true,
  characterData: true,
  subtree: true,
  attributeFilter: ["data-state"],
  attributeOldValue: true,
  characterDataOldValue: true,
});

new MutationObserver(callback) crée un observateur ; observer.observe(target, options) lance l’observation d’un nœud du DOM. La fonction de rappel reçoit un tableau d’objets MutationRecord et l’observateur. Cette API du DOM appartient à la plateforme web, pas à ECMAScript 2024 ; sa disponibilité dépend de l’environnement d’exécution.

childList signale l’ajout ou le retrait d’enfants directs d’un nœud observé (addedNodes, removedNodes). attributes signale l’ajout, la modification ou la suppression d’attributs d’un élément. characterData signale la modification d’un nœud CharacterData existant, par exemple via text.data. Affecter une valeur à textContent sur un élément remplace ses enfants : si leur liste change, le type signalé est childList, et non characterData. subtree: true étend les types de mutations choisis aux descendants ; par défaut, seul target est observé.

attributeFilter contient des noms locaux d’attributs, pas des sélecteurs CSS. Avec un filtre, seuls les attributs listés et sans espace de noms correspondent ; sans filtre, tous les attributs sont pris en compte. attributeOldValue: true et characterDataOldValue: true conservent la valeur précédant la mutation correspondante dans la propriété en lecture seule record.oldValue. Il n’existe ni option oldValue ni champ newValue. oldValue vaut null pour childList, si la conservation de l’ancienne valeur n’a pas été demandée ou si l’attribut n’existait pas auparavant.

childList vaut false par défaut. Si attributes est omis, il passe à true lorsque attributeFilter ou attributeOldValue est fourni ; si characterData est omis, il passe à true lorsque characterDataOldValue est fourni. La présence d’une option d’ancienne valeur suffit, même avec false. Sinon, ces deux types sont désactivés par défaut. observe() lève un TypeError si aucun type n’est actif, si attributes: false est associé à un filtre ou à attributeOldValue: true, ou si characterData: false est associé à characterDataOldValue: true.

Les enregistrements parviennent par lots à la fonction de rappel dans une microtâche, et non pendant la modification du DOM. Avec subtree: true, des inscriptions temporaires permettent de continuer à observer le sous-arbre d’un descendant retiré. La microtâche de notification supprime ces inscriptions lorsqu’elle traite l’observateur, avant tout éventuel appel de la fonction de rappel. Cette suppression ne dépend pas de la livraison d’un enregistrement de retrait : childList peut être désactivé ou takeRecords() peut avoir déjà vidé la file. disconnect() arrête l’observation et abandonne les enregistrements en attente ; pour les récupérer, appelez d’abord takeRecords(), qui vide la file.

Exemples

<!doctype html>
<meta charset="utf-8">
<title>MutationObserver options</title>
<script>
  const root = document.createElement("div");
  const item = document.createElement("span");
  const text = document.createTextNode("before");
  item.setAttribute("data-state", "idle");
  item.append(text);
  root.append(item);

  const observer = new MutationObserver((records, self) => {
    for (const record of records) {
      console.log(JSON.stringify([record.type, record.attributeName, record.oldValue]));
    }
    self.disconnect();
  });

  observer.observe(root, {
    childList: true,
    subtree: true,
    attributeFilter: ["data-state"],
    attributeOldValue: true,
    characterDataOldValue: true,
  });

  item.setAttribute("data-state", "ready");
  item.setAttribute("title", "ignored");
  text.data = "after";
  item.append(document.createElement("em"));
</script>

Résultat

["attributes","data-state","idle"]
["characterData",null,"before"]
["childList",null,null]

Enregistrez l’exemple complet dans un fichier `.html` et ouvrez-le dans un navigateur. Ouvrez la console de développement et rechargez la page. Les nœuds ne sont pas insérés dans la page. Le filtre exclut `title`, et les options de conservation des anciennes valeurs activent `attributes` et `characterData`, qui ont été omis. La fonction de rappel affiche trois enregistrements dans l’ordre des mutations, puis arrête l’observation.

Leçons associées

  • JavaScript · Leçon 31 · Intermédiaire · Version : 3

Sources