MutationObserver.observe()

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 で、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 });