MutationObserver

MutationObserver fournit aux développeurs un moyen d'intercepter les changements dans le DOM. Il a été conçu pour remplacer Mutation Events, défini dans les spécifications DOM3 Events.

Constructeur

MutationObserver()

Constructeur pour instancier un nouvel observateur de mutation DOM.

MutationObserver(
  function callback
);
Paramètres
callback
Fonction qui sera appelée à chaque mutation DOM. L'observateur va appeler cette fonction avec deux arguments. Le premier est un tableau d'objets du type  MutationRecord. Le deuxième est l'instance du MutationObserver.

Méthodes d'instanciation

void observe( Node target, MutationObserverInit options );
void disconnect();
Array takeRecords();

observe()

Inscrit l'instance du MutationObserver afin d'être notifié des mutations DOM du noeud sélectionné.

void observe(
  Node target,
  MutationObserverInit options
);
Paramètres
target
Le Node (noeud) sur lequel doivent être observées les mutations DOM.
options
Un objet du type MutationObserverInit. Il spécifie quelles mutations DOM sont à rapporter.
NOTE : ajouter un observateur sur un élément revient à utiliser addEventListener. Si vous observez un élément plusieurs fois, cela n'a pas d'impact, dans le sens où, si vous observez un élément deux fois la callback ne sera pas appelée deux fois et le disconnect() n'a pas besoin d'être appelé deux fois. En d'autre termes, une fois qu'un élément est observé, l'observer à nouveau avec la même instance ne fera rien. Cependant, si la callback est différente, un nouvel observateur sera ajouté. 

disconnect()

L'instance MutationObserver cesse de recevoir les notifications de mutations DOM. Jusqu'à ce que la méthode  observe() soit appelée à nouveau, les callbacks de l'observateur ne seront pas invoquées.

void disconnect();

takeRecords()

Vide la file des mutations enregistrées du MutationObserver et retourne son contenu. 

Array takeRecords();
Valeur de retour

Retourne un tableau de  MutationRecords.

MutationObserverInit

MutationObserverInit est un objet qui spécifie les propriétés suivantes:

NOTE: Au moins childListattributes, ou characterData doivent être initialisés à true. Sinon, l'erreur "An invalid or illegal string was specified" est renvoyée.
Propriété Description
childList

Initialisé à true si l'ajout ou la suppression des éléments enfants du noeud visé (incluant les nœuds de texte) sont à observer.

attributes

Initialisé à true si les mutations des attributs du noeud visé sont à observer.

characterData Initialisé à true si les mutation des données du noeud visé sont à observer.
subtree Initialisé à true si les enfants du noeud visé sont également à observer.
attributeOldValue Initialisé à true si attributes est initialisé à true et que la valeur des attributs avant mutation du noeud visé doive être enregistrée.
characterDataOldValue Initialisé à true si characterData est initialisé à true et que la valeur des données avant mutation du noeud visé doive être enregistrée.
attributeFilter Initialisé avec un tableau des noms d'attributs locaux (sans namespace) si toutes les mutations d'attributs ne sont pas à observer.

MutationRecord

MutationRecord est l'objet qui sera passé à la callback de l'observateur. Il a les propriétés suivantes :

Propriété Type Description
type String

Retourne attributes si la mutation était une mutation d'attribut, characterData si c'était une mutation d'un noeud CharacterData et childList si c'était la mutation de l'arbre de noeud (éléments enfants).

target Node

Retourne le noeud affecté par la mutation, et cela, en fonction du type. Pour les attributes, c'est l'élément dont l'attribut à changé. Pour childList, c'est le noeud dont les enfants ont changé.

addedNodes NodeList

Retourne les noeuds ajoutés. Ce sera un NodeList vide si aucun noeud n'a été ajouté.

removedNodes NodeList

Retourne les noeuds supprimés. Ce sera un NodeList vide si aucun noeud a été supprimé.

previousSibling Node

Retourne le noeud précédent du noeud qui a été a ajouté ou supprimé, sinon null.

nextSibling Node

Retourne le noeud suivant du noeud qui a été a ajouté ou supprimé, sinon null.

attributeName String

Retourne le nom local de l'attribut qui a changé, ou  null.

attributeNamespace String

Retourne le namespace de l'attribut qui a changé, ou  null.

oldValue String

La valeur de retour dépend du type. Pour les attributes, c'est la valeur antérieure au changement de l'attribut. Pour le characterData, c'est les données antérieures au changement du noeud. Pour childList, c'est null.

Exemple d'utilisation

L'exemple suivant est extrait de ce blog.

// select the target node
var target = document.querySelector('#some-id');
 
// create an observer instance
var observer = new MutationObserver(function(mutations) {
  mutations.forEach(function(mutation) {
    console.log(mutation.type);
  });    
});
 
// configuration of the observer:
var config = { attributes: true, childList: true, characterData: true };
 
// pass in the target node, as well as the observer options
observer.observe(target, config);
 
// later, you can stop observing
observer.disconnect();

Autres articles pour en savoir plus

Compatibilité des navigateurs

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support 18 WebKit
26
14 (14) 11 15 6.0 WebKit
Feature Android Chrome pour  Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support ? 18 WebKit
26
14.0 (14) ? 15

6 WebKit

7

 

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : Goofy, jucrouzet, gregoryRednet, Melkior
 Dernière mise à jour par : Goofy,