MutationObserver.observe()
MutationObserver
の observe()
メソッドは、MutationObserver
コールバックを設定し、与えられたオプションに適合する DOM への変更の通知の受信を開始します。設定によっては、オブザーバーは DOM ツリー内の単一の ノード
を監視したり、そのノードとその子孫ノードの一部またはすべてを監視したりします。
MutationObserver
を停止するには、MutationObserver.disconnect()
を呼び出してください。(これにより、そのコールバックはそれ以降発生しなくなります。)
構文
mutationObserver.observe(target, options)
引数
target
-
DOM ツリー内で変更を監視したり、監視するノードのサブツリーのルートになったりする DOM
ノード
(あるいは、要素
である可能性もあります。) options
-
どの DOM の変更を
mutationObserver
のcallback
に報告するかを記述するオプションを提供する、MutationObserverInit
(en-US)オブジェクト。
戻り値
undefined
例外
TypeError
-
以下のいずれかの状況でスローされます。
-
実際には何も監視されないように
options
が設定されている場合。 (例えば、MutationObserverInit.childList
(en-US)、MutationObserverInit.attributes
(en-US)、MutationObserverInit.characterData
(en-US) が全てfalse
の場合) options.attributes
の値がfalse
(これは属性の変更を監視しないことを示す)であるにも関わらず、attributeOldValue
はtrue
であるか、または、attributeFilter
が存在する場合。characterDataOldValue
はtrue
であるにも関わらず、MutationObserverInit.characterData
(en-US) がfalse
(これは、文字の変更を監視しないことを示す)である場合。
-
実際には何も監視されないように
使用における注意点
MutationObserver の再利用
同一の MutationObserver
で、observe()
を複数回呼び出すことで、DOM ツリーの異なる部分や異なる種類の変更を監視することができます。ただし、注意すべき点がいくつかあります。
- 同じ
MutationObserver
で既に監視されているノードでobserve()
を呼び出すと、新しいオブザーバーがアクティブになる前に、監視されているすべてのターゲットから既存のすべてのオブザーバーが自動的に削除されます。 - 同じ
MutationObserver
がターゲットで使用されていない場合は、既存のオブザーバーを残して新しいオブザーバーを追加します。
ノードの切り離しが行われた際の監視の追従
MutationObserver は、ノード間の直接接続が切断されても、時間の経過とともに目的のノードセットを監視できるようにすることを目的としています。ノードのサブツリーの監視を開始し、そのサブツリーの一部が切り離されて DOM 内の別の場所に移動した場合、切り離されたノードのセグメントを監視し続け、元のサブツリーからノードが切り離される前と同じコールバックを受け取ります。
つまり、監視しているサブツリーからノードが切り離されたことが通知されるまでは、切り離されたサブツリーとそのノードへの変更の通知を受けます。これにより、接続が切断された後、移動したノードやサブツリーの変更を監視し始める前に発生した変更を見逃してしまうことを防ぐことができます。
理論的には、発生した変更を記述した MutationRecord
オブジェクトを追跡していれば、変更を「元に戻す」ことができ、DOM を初期状態に戻すことができるはずです。
例
この例では、MutationObserver
のインスタンス上で observe()
メソッドを呼び出す方法を示します。一度設定したら、ターゲット要素と MutationObserverInit
(en-US) オプションオブジェクトを渡します。
// identify an element to observe
const elementToObserve = document.querySelector("#targetElementId");
// create a new instance of `MutationObserver` named `observer`,
// passing it a callback function
const observer = new MutationObserver(function() {
console.log('callback that runs when observer is triggered');
});
// call `observe()` on that MutationObserver instance,
// passing it the element to observe, and the options object
observer.observe(elementToObserve, {subtree: true, childList: true});
仕様
Specification |
---|
DOM Standard # ref-for-dom-mutationobserver-observe② |
ブラウザ互換性
BCD tables only load in the browser