DOM WHATWG
MutationObserver 的 observe() 方法配置了 MutationObserver 对象的回调方法以开始接收与给定选项匹配的 DOM 变化的通知。根据配置,观察者会观察 DOM 树中的单个 Node,也可能会观察被指定节点的部分或者所有的子孙节点。
要停止 MutationObserver(以便不再触发它的回调方法),需要调用 MutationObserver.disconnect() 方法。
语法
mutationObserver.observe(target[, options])
参数
target- : DOM 树中的一个要观察变化的 DOM Node (可能是一个 Element),或者是被观察的子节点树的根节点。
options-
: 此对象的配置项描述了 DOM 的哪些变化应该报告给
MutationObserver的callback。当调用 MutationObserver.observe 时,childList、attributes和characterData中,必须有一个参数为true。否则会抛出TypeError异常。options的属性如下:subtree- : 当为
true时,将会监听以target为根节点的整个子树。包括子树中所有节点的属性,而不仅仅是针对target。默认值为false。
- : 当为
childList- : 当为
true时,监听target节点中发生的节点的新增与删除(同时,如果subtree为true,会针对整个子树生效)。默认值为false。
- : 当为
attributes- : 当为
true时观察所有监听的节点属性值的变化。当声明了attributeFilter或attributeOldValue时,默认值为true;否则默认值为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配置存在。- MutaitonObserverInit.characterDataOldValue 选项为
true但是 MutationObserverInit.characterData 为false(表示不跟踪字符更改)。
- 配置选项使得实际上不会监视任何内容(例如,如果 MutationObserverInit.childList,MutationObserverInit.attributes 和 MutationObserverInit.characterData 都为
- : 以下任一情况都会抛出异常:
使用说明
复用 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 });
规范
浏览器兼容性
来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。
