CKTIS / JavaScript
MutationObserver : observe(), disconnect() et takeRecords()
Surveillez certaines modifications du DOM, récupérez les enregistrements en attente sans attendre la fonction de rappel et choisissez de les conserver ou non à l’arrêt.
Version : ECMAScript 2024 and the current web platform; runtime support varies
Syntaxe
const observer = new MutationObserver(callback);
observer.observe(target, options);
const records = observer.takeRecords();
observer.disconnect();new MutationObserver(callback) crée un observateur sans démarrer la surveillance. observe(target, options), disconnect() et takeRecords() sont des méthodes d’instance, et non des méthodes statiques. Les modifications correspondantes sont mises en file ; une microtâche de notification transmet un lot à callback(records, observer) au lieu d’appeler la fonction de manière synchrone à chaque modification.
observe(target, options) enregistre un nœud du DOM (Node) et renvoie undefined. D’autres appels permettent d’ajouter des cibles ou de modifier les options pour la même cible. childList surveille les ajouts et suppressions d’enfants directs, attributes les modifications d’attributs, et characterData les modifications des données d’un nœud, comme le contenu d’un nœud texte. subtree: true étend les mêmes règles aux descendants. Des modifications dans une branche retirée peuvent encore être mises en file avant la prochaine microtâche de notification.
attributeFilter limite les noms d’attributs surveillés. attributeOldValue: true et characterDataOldValue: true enregistrent la valeur précédente dans oldValue. Si attributes est omis, la présence de attributeFilter ou de attributeOldValue active la surveillance des attributs. La présence de characterDataOldValue active de même characterData si cette option est omise. observe() lève une TypeError si aucun type de modification n’est activé, si attributes: false est associé à un filtre ou à attributeOldValue: true, ou si characterData: false est associé à characterDataOldValue: true.
takeRecords() renvoie de façon synchrone un tableau d’objets MutationRecord en attente ([] si la file est vide) et vide la file. La méthode n’arrête pas la surveillance et n’appelle pas la fonction de rappel : vous traitez les enregistrements vous-même. disconnect() renvoie undefined, arrête la surveillance de toutes les cibles de cette instance et écarte les enregistrements non transmis. Pour les conserver, appelez takeRecords() juste avant disconnect(). Un nouvel appel à observe() réutilise le même observateur.
Il s’agit d’une API DOM de la plateforme web, pas d’une fonctionnalité d’ECMAScript 2024. Sa disponibilité dépend de l’environnement d’exécution. L’observateur ne donne pas accès à des nœuds autrement inaccessibles, par exemple dans un iframe d’une autre origine.
Exemples
<!doctype html>
<meta charset="utf-8">
<title>MutationObserver example</title>
<script>
const target = document.createElement('div');
const options = { attributes: true, attributeFilter: ['data-state'] };
const observer = new MutationObserver((records, currentObserver) => {
console.log(`callback: ${records.length} ${records[0].attributeName}`);
currentObserver.disconnect();
});
observer.observe(target, options);
target.setAttribute('data-state', 'first');
const [record] = observer.takeRecords();
console.log(`taken: ${record.type} ${record.attributeName}`);
target.setAttribute('data-state', 'discarded');
observer.disconnect();
target.setAttribute('data-state', 'unobserved');
console.log(`remaining: ${observer.takeRecords().length}`);
observer.observe(target, options);
target.setAttribute('data-state', 'delivered');
</script>Résultat
taken: attributes data-state remaining: 0 callback: 1 data-state
Enregistrez l’exemple complet dans un fichier HTML, ouvrez-le dans un navigateur et consultez la console de développement. L’élément n’est pas inséré dans la page. `takeRecords()` récupère le premier enregistrement, `disconnect()` écarte le deuxième et la modification pendant l’arrêt n’est pas enregistrée. Seule la modification après la reprise parvient à la fonction de rappel.
Leçons associées
- JavaScript · Leçon 31 · Intermédiaire · Version : 3