MutationObserver

MutationObserver とは、指定したコールバック関数を DOM の変更時に実行させる API です。この API は、DOM3 Events の仕様で定義されていた Mutation Events を新しく設計し直したものです。

コンストラクタ

MutationObserver()

DOM の変更を検知するオブザーバを生成します。

MutationObserver(
  function callback
);
引数
callback
DOM の変更時に呼び出される関数です。この関数は第 1 引数に MutationRecord の配列を、第 2 引数に MutationObserver インスタンス自身を受け取ります。

インスタンスメソッド

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

補足: 引数 Node target は NodeJS と関係ありません。

observe()

DOM の変更を検知したいノードを指定し、MutationObserver インスタンスを紐づけます。

void observe(
  Node target,
  MutationObserverInit options
);
引数
target
DOM の変更を検知したい Node
options
取得したい変更の種類を指定する MutationObserverInit オブジェクト

補足: MutationObserver インスタンスと対象ノードを変えずに observe() を 2 回実行しても、コールバックは 1 回だけ呼び出され、また disconnect() を 2 回呼び出す必要もありません(addEventListener と同様)。しかし、別の MutationObserver インスタンスであれば、同じノードに別のオブザーバが追加されます。

disconnect()

MutationObserver インスタンスを対象ノードから解除します。同じインスタンスで observe() メソッドを再度呼び出すまで、オブザーバのコールバック関数は実行されません。

void disconnect();

takeRecords()

コールバック関数へ渡される MutationRecord のキューを空にし、キューに入っていた値を返します。

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 対象ノードの変更前の属性値を記録する場合は true にします(attributestrue の時に有効)。
characterDataOldValue 対象ノードの変更前のデータを記録する場合は true にします(characterDatatrue の時に有効)。
attributeFilter すべての属性の変更を監視する必要がない場合は、(名前空間を除いた)属性ローカル名の配列を指定します。

使用例

以下の例は このブログ記事 を参考にしたものです。

// 対象とするノードを取得
const target = document.getElementById('some-id');
 
// オブザーバインスタンスを作成
const observer = new MutationObserver((mutations) => {
  mutations.forEach((mutation) => {
    console.log(mutation.type);
  });    
});
 
// オブザーバの設定
const 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,