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

CKTIS / JavaScript

MutationObserver — observer les changements du DOM

MutationObserver enregistre certains changements du DOM et transmet les enregistrements à une fonction de rappel de manière asynchrone. Découvrez comment observe() configure l’observation, comment takeRecords() vide la file et comment disconnect() arrête l’observation.

Version : ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntaxe

const observer = new MutationObserver((records, observer) => { /* handle records */ });
observer.observe(target, options);
const pending = observer.takeRecords();
observer.disconnect();

MutationObserver est une API du standard DOM, et ne fait pas partie d’ECMAScript lui-même. La fonction de rappel reçoit un tableau d’objets MutationRecord et l’observateur. La notification est mise en file comme microtâche : elle n’est pas remise de manière synchrone pendant un changement ; un appel peut contenir plusieurs enregistrements. La présence de Node 24 dans un dépôt ne prouve pas que cette API de navigateur y est disponible.

MutationObserver.observe, appelé sous la forme observer.observe(target, options), sélectionne un nœud et les types de mutations : childList suit l’ajout et le retrait d’enfants, attributes suit les attributs et characterData les données des nœuds texte et assimilés. subtree: true inclut les descendants. Au moins un type doit être activé après application des valeurs par défaut ; sinon, une TypeError est levée. attributeFilter limite les noms d’attributs ; attributeOldValue et characterDataOldValue demandent les valeurs précédentes. Les options liées aux attributs ou aux données peuvent activer implicitement le type d’observation correspondant, mais des réglages explicitement contradictoires provoquent une TypeError.

MutationObserver.takeRecords, appelé sous la forme observer.takeRecords(), renvoie de façon synchrone les enregistrements en attente et vide la file, sans appeler la fonction de rappel ni arrêter l’observation. MutationObserver.disconnect, appelé sous la forme observer.disconnect(), arrête toutes les observations de cet objet et supprime les enregistrements en attente. Récupérez-les avant si vous en avez besoin. L’objet peut être redémarré avec observe().

L’exemple observe un élément détaché, récupère son enregistrement avant la remise de la notification et arrête l’observation. oldValue vaut null, car l’attribut n’existait pas auparavant. Limitez la portée de l’observation ; les mutations effectuées par la fonction de rappel peuvent produire d’autres notifications.

Exemples

{
  const target = document.createElement('div');
  const observer = new MutationObserver((records) => {
    console.log('callback:', records.length);
  });

  observer.observe(target, {
    attributes: true,
    attributeFilter: ['data-state'],
    attributeOldValue: true
  });

  target.setAttribute('data-state', 'ready');
  const records = observer.takeRecords();
  console.log(JSON.stringify(records.map((record) => ({
    type: record.type,
    attributeName: record.attributeName,
    oldValue: record.oldValue
  }))));

  observer.disconnect();
  target.setAttribute('data-state', 'done');
  console.log(observer.takeRecords().length);
}

Résultat

[{"type":"attributes","attributeName":"data-state","oldValue":null}]
0

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources