MutationObserver.observe()
MutationObserver
的 observe()
方法配置了 MutationObserver
对象的回调方法以开始接收与给定选项匹配的 DOM 变化的通知。根据配置,观察者会观察 DOM 树中的单个 Node
,也可能会观察被指定节点的部分或者所有的子孙节点。
要停止 MutationObserver
(以便不再触发它的回调方法),需要调用 MutationObserver.disconnect()
方法。
语法
mutationObserver.observe(target[, options])
参数
target
options
-
此对象的配置项描述了 DOM 的哪些变化应该报告给
MutationObserver
的callback
。当调用observe()
时,childList
、attributes
和characterData
中,必须有一个参数为true
。否则会抛出TypeError
异常。options
的属性如下:subtree
可选-
当为
true
时,将会监听以target
为根节点的整个子树。包括子树中所有节点的属性,而不仅仅是针对target
。默认值为false
。 childList
可选-
当为
true
时,监听target
节点中发生的节点的新增与删除(同时,如果subtree
为true
,会针对整个子树生效)。默认值为false
。 attributes
可选-
当为
true
时观察所有监听的节点属性值的变化。默认值为true
,当声明了attributeFilter
或attributeOldValue
,默认值则为false
。 attributeFilter
可选-
一个用于声明哪些属性名会被监听的数组。如果不声明该属性,所有属性的变化都将触发通知。
attributeOldValue
可选-
当为
true
时,记录上一次被监听的节点的属性变化;可查阅监听属性值了解关于观察属性变化和属性值记录的详情。默认值为false
。 characterData
可选-
当为
true
时,监听声明的target
节点上所有字符的变化。默认值为true
,如果声明了characterDataOldValue
,默认值则为false
characterDataOldValue
可选-
当为
true
时,记录前一个被监听的节点中发生的文本变化。默认值为false
返回值
undefined
。
异常
TypeError
-
以下任一情况都会抛出异常:
- 配置选项使得实际上不会监视任何内容(例如,如果
MutationObserverInit.childList
,MutationObserverInit.attributes
和MutationObserverInit.characterData
都为false
)。 attributes
选项为false
(表示不监视属性更改)但是attributeOldValue
为true
并且/或者attributeFilter
配置存在。characterDataOldValue
选项为true
但是MutationObserverInit.characterData
为false
(表示不跟踪字符更改)。
- 配置选项使得实际上不会监视任何内容(例如,如果
使用说明
复用 MutationObserver
你可以多次调用同一个 MutationObserver
对象的 observe()
方法,来观察 DOM 树中不同部分的变化,和/或不同类型的变化。有一些需要注意的注意事项:
- 如果在已经被同一
MutationObserver
观察的节点上调用observe()
方法,则在激活新观察者之前,所有现有观察者将自动从所有正在观察的目标中移除。 - 如果同一个
MutationObserver
还没有作用在 target 上,则保留现有观察者并添加新观察者。
当节点断开连接时继续观察节点
MutationObserver
旨在让你能够随着时间的推移观察所需的节点集,即使这些节点之间的直接连接被切断。如果你开始观察节点的子树,并且该子树的一部分被分离并移动到 DOM 中的其他位置,你将继续观察分离的节点段,接收与节点从原始子树分离之前相同的回调。
换句话说,在你收到有关节点从被观察子树中拆分的通知之前,你将收到有关该拆分子树及其节点的更改的通知。这可以防止你丢失在切断连接之后以及在你有机会专门开始观察已移动的节点或子树之前发生的变化。
这意味着理论上如果你跟踪描述发生的变化的 MutationRecord
对象,你就可以“撤销”这些改动,将 DOM 恢复到初始状态。
示例
在此例子中,将为你演示如何在实例 MutationObserver
中调用 observe()
方法,一旦设置后,会传给他一个目标元素和一个 MutationObserverInit
配置对象。
// 得到要观察的元素
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 });
规范
Specification |
---|
DOM Standard # ref-for-dom-mutationobserver-observe② |
浏览器兼容性
BCD tables only load in the browser