1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
|
---
title: MutationObserver.observe()
slug: Web/API/MutationObserver/observe
translation_of: Web/API/MutationObserver/observe
---
<div>{{APIRef("DOM WHATWG")}}</div>
<p><span class="seoSummary">{{domxref("MutationObserver")}} の <code><strong>observe()</strong></code> メソッドは、<code>MutationObserver</code> コールバックを設定し、与えられたオプションに適合するDOMへの変更の通知の受信を開始します。設定によっては、オブザーバーは</span>DOM ツリー内の単一の {{domxref("Node", "ノード")}} を監視したり、そのノードとその子孫ノードの一部またはすべてを監視したりします。</p>
<p><code>MutationObserver</code> を停止するには、{{domxref("MutationObserver.disconnect()")}} を呼び出してください。(これにより、そのコールバックはそれ以降発生しなくなります。) </p>
<ul>
</ul>
<h2 id="構文">構文</h2>
<pre class="syntaxbox notranslate"><var>mutationObserver</var>.observe(<var>target</var>, <var>options</var>)
</pre>
<h3 id="引数">引数</h3>
<dl>
<dt><code><var>target</var></code></dt>
<dd>DOM ツリー内で変更を監視したり、監視するノードのサブツリーのルートになったりするDOM{{domxref("Node", "ノード")}} (あるいは、{{domxref("Element", "要素")}}である可能性もあります。)</dd>
<dt><code><var>options</var></code></dt>
<dd>どのDOMの変更を<code><var>mutationObserver</var></code>の<code><var>callback</var></code>に報告するかを記述するオプションを提供する、{{domxref("MutationObserverInit")}}オブジェクト。</dd>
</dl>
<h3 id="戻り値">戻り値</h3>
<p><code>undefined</code></p>
<h3 id="例外">例外</h3>
<dl>
<dt>{{jsxref('TypeError')}}</dt>
<dd>以下のいずれかの状況でスローされます。
<ul>
<li>実際には何も監視されないように<code><var>options</var></code>が設定されている場合。<br>
(例えば、 {{domxref("MutationObserverInit.childList")}}、 {{domxref("MutationObserverInit.attributes")}}、{{domxref("MutationObserverInit.characterData")}} が全て<code>false</code>の場合)</li>
<li><code><var>options.</var>attributes</code> の値が <code>false</code> (これは属性の変更を監視しないことを示す)であるにも関わらず、<code>attributeOldValue</code> は <code>true</code> であるか、または、<code>attributeFilter</code> が存在する場合。</li>
<li>{{domxref("MutaitonObserverInit.characterDataOldValue", "characterDataOldValue")}} は <code>true</code> であるにも関わらず、 {{domxref("MutationObserverInit.characterData")}} が <code>false</code> (これは、文字の変更を監視しないことを示す)である場合。</li>
</ul>
</dd>
</dl>
<h2 id="使用における注意点">使用における注意点</h2>
<h3 id="MutationObserverの再利用">MutationObserverの再利用</h3>
<p>同一の <code>MutationObserver</code> で、<code>observe()</code> を複数回呼び出すことで、DOM ツリーの異なる部分や異なる種類の変更を監視することができます。ただし、注意すべき点がいくつかあります。</p>
<ul>
<li>同じ<code>MutationObserver</code>で既に監視されているノードで<code>observe()</code>を呼び出すと、新しいオブザーバーがアクティブになる前に、監視されているすべてのターゲットから既存のすべてのオブザーバーが自動的に削除されます。</li>
<li>同じ<code>MutationObserver</code>がターゲットで使用されていない場合は、既存のオブザーバーを残して新しいオブザーバーを追加します。</li>
</ul>
<h3 id="ノードの切り離しが行われた際の監視の追従">ノードの切り離しが行われた際の監視の追従</h3>
<p>MutationObserverは、ノード間の直接接続が切断されても、時間の経過とともに目的のノードセットを監視できるようにすることを目的としています。ノードのサブツリーの監視を開始し、そのサブツリーの一部が切り離されて DOM 内の別の場所に移動した場合、切り離されたノードのセグメントを監視し続け、元のサブツリーからノードが切り離される前と同じコールバックを受け取ります。</p>
<p>つまり、監視しているサブツリーからノードが切り離されたことが通知されるまでは、切り離されたサブツリーとそのノードへの変更の通知を受けます。これにより、接続が切断された後、移動したノードやサブツリーの変更を監視し始める前に発生した変更を見逃してしまうことを防ぐことができます。</p>
<p>理論的には、発生した変更を記述した {{domxref("MutationRecord")}} オブジェクトを追跡していれば、変更を「元に戻す」ことができ、DOM を初期状態に戻すことができるはずです。</p>
<h2 id="例">例</h2>
<p>この例では、{{domxref("MutationObserver")}} のインスタンス上で<code><strong>observe()</strong></code> メソッドを呼び出す方法を示します。一度設定したら、ターゲット要素と {{domxref("MutationObserverInit")}} オプションオブジェクトを渡します。</p>
<pre class="brush: js notranslate">// 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});</pre>
<h2 id="Specifications" name="Specifications">仕様</h2>
<table class="standard-table">
<thead>
<tr>
<th scope="col">Specification</th>
<th scope="col">Status</th>
<th scope="col">Comment</th>
</tr>
</thead>
<tbody>
<tr>
<td>{{SpecName('DOM WHATWG', '#dom-mutationobserver-observe', 'MutationObserver.observe()')}}</td>
<td>{{ Spec2('DOM WHATWG') }}</td>
<td></td>
</tr>
</tbody>
</table>
<h2 id="ブラウザ互換性">ブラウザ互換性</h2>
<p>{{Compat("api.MutationObserver.observe")}}</p>
|
