MutationObserver API

た入场券 2023-02-22 03:41 31阅读 0赞

One of my favorite web tricks was using CSS and JavaScript to detect insertion and removal of a DOM node, detailed in [Detect DOM Node Insertions with JavaScript and CSS Animations][].  The technique and blog post were published during a time when we didn't have a reasonable API for detecting such events.  Nowadays we have [`MutationObserver`][MutationObserver], an API made to efficiently detect loads of node operations.  Let's have a look!

我最喜欢的网络技巧之一是使用CSS和JavaScript来检测DOM节点的插入和移除，有关详细信息，请参见[使用JavaScript和CSS动画检测DOM节点插入][Detect DOM Node Insertions with JavaScript and CSS Animations] 。 该技术和博客文章是在我们没有合理的API来检测此类事件的时候发布的。 如今，我们有了[`MutationObserver`][MutationObserver] ，该API旨在有效检测节点操作的负载。 我们来看一下！

## 基本的`MutationObserver` API **(**Basic `MutationObserver` API**)** ##

The `MutationObserver` API is a bit complicated for me but here's the basic setup:

`MutationObserver` API对我来说有点复杂，但这是基本设置：

There's a lot to using the `MutationObserver`, but the breakdown is:

使用`MutationObserver`的工作很多，但细目如下：

*  Create an instance of `MutationObserver` with a callback to handle any event thrown its way
    
    创建一个带有回调的`MutationObserver`实例，以处理抛出的所有事件
 *  Create a set of options for the `MutationObserver`
    
    为`MutationObserver`创建一组选项
 *  Call the `observe` method of the `MutationObserver` instance, passing it the node to listen to (..and its children) and the option list.
    
    调用`MutationObserver`实例的`observe`方法，向其传递要侦听的节点(..及其子节点)和选项列表。
 *  At the time you want to stop observing, call `disconnect`
    
    您要停止观察时，请`disconnect`

## `MutationObserver`选项 **(**`MutationObserver` Options**)** ##

MDN provides detail on the options for `MutationObserver`:

MDN提供有关`MutationObserver`选项的详细信息：

*  `childList`: Set to true if additions and removals of the target node's child elements (including text nodes) are to be observed.
    
    `childList` ：如果要观察到目标节点的子元素(包括文本节点)的添加和移除，则设置为true。
 *  `attributes`: Set to true if mutations to target's attributes are to be observed.
    
    `attributes` ：如果要观察到目标属性的变异，则设置为true。
 *  `characterData Set`: to true if mutations to target's data are to be observed.
    
    `characterData Set` ：如果要观察到目标数据的突变，则为true。
 *  `subtree`: Set to true if mutations to not just target, but also target's descendants are to be observed.
    
    `subtree` ：如果不仅要观察目标，还要观察目标的后代，则设置为true。
 *  `attributeOldValue`: Set to true if attributes is set to true and target's attribute value before the mutation needs to be recorded.
    
    `attributeOldValue` ：如果属性设置为true且需要记录突变之前目标的属性值，则设置为true。
 *  `characterDataOldValue`: Set to true if characterData is set to true and target's data before the mutation needs to be recorded.
    
    `characterDataOldValue` ：如果characterData设置为true，并且需要记录突变之前的目标数据，则设置为true。
 *  `attributeFilter`: Set to an array of attribute local names (without namespace) if not all attribute mutations need to be observed.
    
    `attributeFilter` ：如果不需要观察所有的属性突变，则设置为属性本地名称(无名称空间)的数组。

That's a lot to be aware of when listening to one node and/or child nodes!

在侦听一个节点和/或子节点时要注意很多！

## MutationRecord： `MutationObserver`处理程序结果 **(**MutationRecord:  `MutationObserver` Handler Results**)** ##

The resulting object when a mutation is observed is detailed as well:

观察到突变时产生的对象也很详细：

*  `type (String)`: Returns attributes if the mutation was an attribute mutation, characterData if it was a mutation to a CharacterData node, and childList if it was a mutation to the tree of nodes.
    
    `type (String)` ：如果突变是属性突变，则返回属性；如果CharacterData是CharacterData节点的突变，则返回characterData；如果是节点树的突变，则返回childList。
 *  `target (Node)`: Returns the node the mutation affected, depending on the type. For attributes, it is the element whose attribute changed. For characterData, it is the CharacterData node. For childList, it is the node whose children changed.
    
    `target (Node)` ：根据类型返回受突变影响的节点。 对于属性，它是其属性已更改的元素。 对于characterData，它是CharacterData节点。 对于childList，它是其子项已更改的节点。
 *  `addedNodes (NodeList)`: Return the nodes added. Will be an empty NodeList if no nodes were added.
    
    `addedNodes (NodeList)` ：返回添加的节点。 如果未添加任何节点，则该节点将为空。
 *  `removedNodes (NodeList)`: Return the nodes removed. Will be an empty NodeList if no nodes were removed.
    
    `removedNodes (NodeList)` ：返回已删除的节点。 如果未删除任何节点，则该节点将为空。
 *  `previousSibling (Node)`: Return the previous sibling of the added or removed nodes, or null.
    
    `previousSibling (Node)` ：返回添加或删除的节点的上一个兄弟节点，或者为null。
 *  `nextSibling (Node)`: Return the next sibling of the added or removed nodes, or null.
    
    `nextSibling (Node)` ：返回添加或删除的节点的下一个同级，或者为null。
 *  `attributeName (String)`: Returns the local name of the changed attribute, or null.
    
    `attributeName (String)` ：返回已更改属性的本地名称，或者为null。
 *  `attributeNamespace (String)`: Returns the namespace of the changed attribute, or null.
    
    `attributeNamespace (String)` ：返回已更改属性的名称空间，或者为null。
 *  `oldValue (String)`: The return value depends on the type. For attributes, it is the value of the changed attribute before the change. For characterData, it is the data of the changed node before the change. For childList, it is null.
    
    `oldValue (String)` ：返回值取决于类型。 对于属性，它是更改前更改的属性的值。 对于characterData，它是更改之前更改的节点的数据。 对于childList，它为null。

Whew.  So let's take look at some realistic use cases of `MutationObserver`.

ew。 因此，让我们看一下`MutationObserver`一些实际用例。

## 检测何时插入节点 **(**Detect When a Node is Inserted**)** ##

The use case in my [Detect DOM Node Insertions with JavaScript and CSS Animations][] post was detecting node insertion, so let's create a snippet which detects node insertion:

我的《使用[JavaScript和CSS动画检测DOM节点插入][Detect DOM Node Insertions with JavaScript and CSS Animations] 》一文中的用例是检测节点插入，因此让我们创建一个片段来检测节点插入：

// Let's add a sample node to see what the MutationRecord looks like
    // document.body.appendChild(document.createElement('li'));
    
    {
    	addedNodes: NodeList[1], // The added node is in this NodeList
    	attributeName: null,
    	attributeNamespace: null,
    	nextSibling: null,
    	oldValue: null,
    	previousSibling: text,
    	removedNodes: NodeList[0],
    	target: body.document,
    	type: "childList"
    }

The resulting MutationRecord shows `addedNodes: NodeList[1]`, meaning that a node has been added somewhere lower in the tree.  The `type` is `childList`.

生成的MutationRecord显示出`addedNodes: NodeList[1]` ，这意味着已在树的较低位置添加了一个节点。 `type`是`childList` 。

## 检测何时删除节点 **(**Detect When a Node is Removed**)** ##

Removing a node shows the following MutationRecord:

删除节点将显示以下MutationRecord：

// Now let's explore the MutationRecord when a node is removed
    // document.body.removeChild(document.querySelector('div'))
    
    {
    	addedNodes: NodeList[0],
    	attributeName: null,
    	attributeNamespace: null,
    	nextSibling: text,
    	oldValue: null,
    	previousSibling: null,
    	removedNodes: NodeList[1], // The removed node is in this NodeList
    	target: body.document,
    	type: "childList"
    }

This action also shows a `type` of `childList` but now `removeNodes` now has the `NodeList[1]`, a `NodeList` with the removed node.

此操作还显示了`childList`的`type` ，但是`removeNodes`现在具有`NodeList[1]` ，即具有已删除节点的`NodeList` 。

## 检测属性更改 **(**Detect Attribute Changes**)** ##

If an attribute is changed on any element, you'll be quick to know about it; the MutationRecord will show:

如果在任何元素上更改了属性，您将很快了解它。 MutationRecord将显示：

// What do attribute changes look like?
    // document.body.setAttribute('id', 'booooody');
    
    {
    	addedNodes: NodeList[0],
    	attributeName: "id",
    	attributeNamespace: null,
    	nextSibling: null,
    	oldValue: null,
    	previousSibling: null,
    	removedNodes: NodeList[0],
    	target: body#booooody.document,
    	type: "attributes"
    }

Also note that the `target` will show the node for which the attributes was changed.  The `oldValue` will display its former value and while a normal `getAttribute` check give you the new attributes value.

另请注意， `target`将显示其属性已更改的节点。 `oldValue`将显示其以前的值，而常规的`getAttribute`检查将为您提供新的属性值。

## 别听了！ **(**Stop Listening!**)** ##

If you're looking to write the ultimate efficient app, you'll only be adding listeners for the period you need them and then removing them when you're done:

如果您要编写最终高效的应用程序，则只需在所需的时间内添加监听器，然后在完成时将其删除：

observer.disconnect();

The `MutationObserver` instance has a `disconnect` method to stop listening.  Since your app may have many, many DOM operations, you may want the power to disconnect your listener for the duration of the time your user interacts with the page.

`MutationObserver`实例具有`disconnect`方法以停止侦听。 由于您的应用程序可能有很多很多DOM操作，因此您可能希望在用户与页面进行交互的过程中断开监听器的连接。

The `MutationObserver` API seems a tad verbose but it's powerful, informative, and ultimately hack free.  Daniel Buchner's brilliant original "hack" provides better support for node addition and removal but `MutationObserver` should probably be used if possible.

`MutationObserver` API似乎有点冗长，但功能强大，信息量大，并且最终不受黑客攻击。 丹尼尔·布赫纳(Daniel Buchner)出色的原创“ hack”为节点添加和删除提供了更好的支持，但如果可能的话，应该使用`MutationObserver` 。

> 翻译自: [https://davidwalsh.name/mutationobserver-api][https_davidwalsh.name_mutationobserver-api]

[Detect DOM Node Insertions with JavaScript and CSS Animations]: https://davidwalsh.name/detect-node-insertion
[MutationObserver]: https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver
[https_davidwalsh.name_mutationobserver-api]: https://davidwalsh.name/mutationobserver-api