MutationObserver.observe()

MutationObserver の observe() メソッドは、MutationObserver コールバックを設定し、与えられたオプションに適合するDOMへの変更の通知の受信を開始します。設定によっては、オブザーバーはDOM ツリー内の単一の ノード を監視したり、そのノードとその子孫ノードの一部またはすべてを監視したりします。

MutationObserver を停止するには、MutationObserver.disconnect() を呼び出してください。(これにより、そのコールバックはそれ以降発生しなくなります。) 

構文

mutationObserver.observe(target, options)

引数

target
DOM ツリー内で変更を監視したり、監視するノードのサブツリーのルートになったりするDOMノード (あるいは、要素である可能性もあります。)
options
どのDOMの変更をmutationObservercallbackに報告するかを記述するオプションを提供する、MutationObserverInit (en-US)オブジェクト。

戻り値

undefined

例外

TypeError
以下のいずれかの状況でスローされます。

使用における注意点

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 Status Comment
DOM
MutationObserver.observe() の定義
現行の標準

ブラウザ互換性

BCD tables only load in the browser