blob: 5c6f18ba9423df638ef8b57a56cb26c763bef266 (
plain)
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
107
108
109
110
|
---
title: MutationObserver.observe()
slug: Web/API/MutationObserver/observe
tags:
- API
- DOM
- MutationObserver
- Node
- 参考
- 变化
- 方法
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>
<h2 id="语法">语法</h2>
<pre class="syntaxbox"><em>mutationObserver</em>.observe(<em>target</em>[, <em>options</em>])
</pre>
<h3 id="参数">参数</h3>
<dl>
<dt><code>target</code></dt>
<dd>DOM树中的一个要观察变化的DOM {{domxref("Node")}} (可能是一个{{domxref("Element")}}) , 或者是被观察的子节点树的根节点。</dd>
<dt><code>options</code> {{optional_inline}}</dt>
<dd>一个可选的{{domxref("MutationObserverInit")}} 对象，此对象的配置项描述了DOM的哪些变化应该提供给当前观察者的<code>callback</code>。</dd>
</dl>
<h3 id="返回值">返回值</h3>
<p><code>undefined</code>。</p>
<h3 id="异常">异常</h3>
<dl>
<dt><code>TypeError</code></dt>
<dd>以下任一情况都会抛出异常:
<ul>
<li>配置选项使得实际上不会监视任何内容（例如，如果 {{domxref("MutationObserverInit.childList")}}，{{domxref("MutationObserverInit.attributes")}} 和 {{domxref("MutationObserverInit.characterData")}} 都为 <code>false</code>）。</li>
<li><code>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> 还没有作用在 target 上，则保留现有观察者并添加新观察者。</li>
</ul>
<h3 id="当节点断开连接时继续观察节点">当节点断开连接时继续观察节点</h3>
<p><code>MutationObserver</code> 旨在让您能够随着时间的推移观察所需的节点集，即使这些节点之间的直接连接被切断。如果你开始观察节点的子树，并且该子树的一部分被分离并移动到DOM中的其他位置，你将继续观察分离的节点段，接收与节点从原始子树分离之前相同的回调。</p>
<p>换句话说，在你收到有关节点从被观察子树中拆分的通知之前，你将收到有关该拆分子树及其节点的更改的通知。这可以防止你丢失在切断连接之后以及在你有机会专门开始观察已移动的节点或子树之前发生的变化。</p>
<p>这意味着理论上如果你跟踪描述发生的变化的{{domxref("MutationRecord")}}对象，你就可以“撤销”这些改动，将DOM恢复到初始状态。</p>
<h2 id="示例">示例</h2>
<p>在此例子中，将为你演示如何在实例 {{domxref("MutationObserver")}} 中调用<strong><code>observe()</code> </strong>方法，一旦设置后，会传给他一个目标元素和一个 {{domxref("MutationObserverInit")}} 配置对象。</p>
<pre class="brush: js">// 得到要观察的元素
var elementToObserve = document.querySelector("#targetElementId");
// 创建一个叫 `observer` 的新 `MutationObserver` 实例，
// 并将回调函数传给它
var observer = new MutationObserver(function() {
console.log('callback that runs when observer is triggered');
});
// 在 MutationObserver 实例上调用 `observe` 方法，
// 并将要观察的元素与选项传给此方法
observer.observe(elementToObserve, {subtree: true, childList: true});</pre>
<h2 id="Specifications" name="Specifications">规范</h2>
<table class="standard-table">
<thead>
<tr>
<th scope="col">规范</th>
<th scope="col">状态</th>
<th scope="col">备注</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>
<div class="hidden">此页面上的兼容性表是根据结构化数据生成的。如果您想为数据做出贡献，请查看 <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> 并向我们发送拉取请求。</div>
<p>{{Compat("api.MutationObserver.observe")}}</p>
|
