MutationObserver

MutationObserverDOM 内の変更に対応する方法を開発者に提供します。これは DOM3 Events 仕様書で定義された Mutation Events を置き換えるものとして設計されたものです。

コンストラクタ

MutationObserver()

新しい DOM 変更オブザーバのインスタンスを作成するためのコンストラクタ。

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

インスタンスメソッド

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

observe()

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

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

disconnect()

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

void disconnect();

takeRecords()

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

Array takeRecords();
戻り値

MutationRecord の配列。

MutationObserverInit

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

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

MutationRecord

MutationRecord はオブザーバのコールバック関数に渡されるオブジェクトです。これは以下のプロパティを持ちます。

プロパティ 意味
type String 属性値の変更の場合は attributesCharacterData ノードに対する変更の場合は characterData、ノードのツリーに対する変更の場合は childList を返します。
target Node 変更の影響を受けたノードを返します。値は type によります。attributes の場合、属性が変更された要素となります。characterData の場合、CharacterData ノードとなります。childList の場合、子ノードが変更されたノードとなります。
addedNodes NodeList 追加されたノード、もしくは null を返します。
removedNodes NodeList 削除されたノード、もしくは null を返します。
previousSibling Node 追加あるいは削除されたノードの直前にあるノード、もしくは null を返します。
nextSibling Node 追加あるいは削除されたノードの直後にあるノード、もしくは null を返します。
attributeName String 変更された属性のローカル名、もしくは null を返します。
attributeNamespace String 変更された属性の名前空間、もしくは null を返します。
oldValue String 戻り値は type によります。attributes の場合、変更された属性の変更前の属性値となります。characterData の場合、変更されたノードの変更前のデータとなります。childList の場合、null となります。

使い方の例

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

// 対象ノードを選択
var target = document.querySelector('#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();

関連情報

ブラウザ実装状況

機能 Chrome Firefox (Gecko) Internet Explorer Opera Safari
基本実装 (有) webkit 14 (14) ? ? (有)
機能 Android Android 版 Chrome Android 版 Firefox (Gecko) IE Mobile Opera Mobile Safari Mobile
基本実装 ? ? 14.0 (14) ? ? ?

Document Tags and Contributors

Contributors to this page: ethertank, Yoshino
最終更新者: ethertank,