MutationObserver

MutationObserver を用いることで、DOM の中で生じた変更に対応することができます。この API は、DOM3 Events 仕様書で定義された Mutation Events を置き換えるものとして設計されています。

コンストラクタ

MutationObserver()

DOM の変更を監視するオブザーバを新しく生成するコンストラクタです。

MutationObserver(
  function callback
);
引数
callback
DOM に変更が行われるたびに呼び出される関数。オブザーバはこの関数に引数を 2 つ与えて呼び出します。1 番目はオブジェクトの配列で、それぞれ MutationRecord の形式を取ります。2 番目はこの MutationObserver インスタンスです。

インスタンスメソッド

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

補足: 引数 Node target を NodeJS と混同しないでください。

observe()

MutationObserver インスタンスを登録し、指定したノードにおける DOM の変更通知を受け取ります。

void observe(
  Node target,
  MutationObserverInit options
);
引数
target
DOM の変更を監視する Node
options
DOM の変更を報告する MutationObserverInit オブジェクト。

補足: ある要素を同一の方法で複数回 observe した場合、そこで行われる observer の追加は addEventListener の場合とほぼ同じです。つまり、同じ要素を 2 回 observe した場合、コールバックが 2 回発火することはなく、また disconnect() を 2 回呼び出す必要もありません。言い換えれば、ある要素が一度 observe された後は、同じ observer のインスタンスで再度 observe しても何も変わらないということです。しかし、コールバックのオブジェクトが異なっていれば、当然ながら別の observer が追加されます。

disconnect()

MutationObserver インスタンスが DOM の変更通知を受け取るのを中止します。observe() メソッドが再度使われるまで、オブザーバのコールバック関数は呼び出されなくなります。

void disconnect();

takeRecords()

MutationObserver インスタンスの記録キューを空にして、そこに記録されていた内容を返します。

Array takeRecords();
戻り値

MutationRecord の配列。

MutationObserverInit

MutationObserverInit は以下のプロパティを指定できるオブジェクトです。

補足: 少なくとも childList / attributes / characterData には true を設定しなければなりません。設定しないと "An invalid or illegal string was specified" のエラーが投げられます。

プロパティ 意味
childList 対象ノードの子ノード(テキストノードも含む)に対する追加・削除を監視する場合は true にします。
attributes 対象ノードの属性に対する変更を監視する場合は true にします。
characterData 対象ノードのデータに対する変更を監視する場合は true にします。
subtree 対象ノードだけでなく、対象ノードの子孫ノードに対する変更も監視する場合は true にします。
attributeOldValue attributestrue に設定した上で、対象ノードの変更前の属性値を記録する場合は true にします。
characterDataOldValue characterDatatrue に設定した上で、対象ノードの変更前のデータを記録する場合は true にします。
attributeFilter すべての属性の変更を監視する必要がない場合は、(名前空間を除いた)属性ローカル名の配列を指定します。

使用例

以下の例は このブログ記事 から引用したものです。

// 対象ノードを選択
var target = document.getElementById('some-id');
 
// オブザーバインスタンスを作成
var observer = new MutationObserver(function(mutations) {
  mutations.forEach(function(mutation) {
    console.log(mutation.type);
  });    
});
 
// オブザーバの設定
var config = { attributes: true, childList: true, characterData: true }
 
// 対象ノードとオブザーバの設定を渡す
observer.observe(target, config);
 
// 後ほど、監視を中止
observer.disconnect();

関連情報

仕様

仕様書 策定状況 備考
DOM
MutationObserver の定義
現行の標準  
DOM4
MutationObserver の定義
勧告  

ブラウザ実装状況

機能 Chrome Firefox (Gecko) Internet Explorer Opera Safari
基本サポート 18 -webkit
26
14 (14) 11 15 6.0 -webkit
機能 Android Chrome for Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
基本サポート 4.4 18 -webkit
26
14.0 (14) 11 (8.1) 15 6 -webkit
7

ドキュメントのタグと貢献者

 このページの貢献者: hashedhyphen, ethertank, kohei.yoshino
 最終更新者: hashedhyphen,