MutationObserver fournit un moyen d’intercepter les changements dans le DOM. Il a été conçu pour remplacer les Mutation Events définis dans la spécification DOM3 Events.
Constructeur
MutationObserver()
Le constructeur permettant d’instancier un nouvel observateur de mutations DOM.
new MutationObserver( function callback );
Paramètres
callback- Une fonction qui sera appelée à chaque mutation du DOM. L’observateur appellera cette fonction avec deux arguments. Le premier est un tableau d’objets de type
MutationRecord; le second est l’instance deMutationObserver.
Méthodes d’instance
void observe( |
void disconnect(); |
Array takeRecords(); |
observe()
Inscrit l’instance du MutationObserver afin d’être notifié des mutations DOM du nœud sélectionné.
void observe(Nodetarget,MutationObserverInitoptions );
Paramètres
target- Le
Node(nœud) 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 vous n’aurez pas besoin d’appeler disconnect() deux fois. En d’autres termes, une fois qu’un élément est observé, l’observer à nouveau avec la même instance n’a pas d’effet. 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 MutationRecord.
MutationObserverInit
MutationObserverInit est un objet pouvant avoir les propriétés suivantes :
Note : Au moins une propriété parmi
childList, attributes ou characterData doit être initialisée à true, sinon l’erreur An invalid or illegal string was specified sera émise.| Propriété | Description |
childList |
true si l’ajout ou la suppression des éléments enfants du nœud visé (incluant les nœuds de texte) sont à observer. |
attributes |
true si les mutations d’attributs du nœud visé sont à observer. |
characterData |
true si les mutation de texte du nœud visé sont à observer. |
subtree |
true si les descendants du nœud visé sont également à observer. |
attributeOldValue |
true si attributes est true et si la valeur des attributs avant mutation doit être enregistrée. |
characterDataOldValue |
true si characterData est true et si la valeur des données avant mutation doit être enregistrée. |
attributeFilter |
Spécifiez un tableau de noms d’attributs locaux (sans namespace) si vous souhaitez n’observer les mutations que sur une partie des attributs. |
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 nœud CharacterData (nœud de texte), et childList si c’était une mutation du sous-arbre des éléments descendants. |
target |
|
Retourne le nœud affecté par la mutation, en fonction du type. Pour attribute, c’est l’élément dont l’attribut à changé. Pour childList, c’est le nœud dont les descendants ont changé. |
addedNodes |
|
Retourne les nœuds ajoutés. Ce sera une NodeList vide si aucun nœud n’a été ajouté. |
removedNodes |
|
Retourne les nœuds supprimés. Ce sera une NodeList vide si aucun nœud n’a été supprimé. |
previousSibling |
|
Retourne le nœud précédent le nœud qui a été a ajouté ou supprimé, ou null. |
nextSibling |
|
Retourne le nœud suivant le nœud qui a été a ajouté ou supprimé, ou 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 attribute, c’est la valeur antérieure au changement de l’attribut. Pour characterData, c’est les données antérieures au changement du texte. 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
- A brief overview
- A more in-depth discussion
- A screencast by Chromium developer Rafael Weinstein
- The mutation summary library
- The DOM standard which defines the
MutationObserverinterface