From 33058f2b292b3a581333bdfb21b8f671898c5060 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:40:17 -0500 Subject: initial commit --- .../web/api/mutationobserver/disconnect/index.html | 74 ++++++++++++++ files/zh-cn/web/api/mutationobserver/index.html | 110 +++++++++++++++++++++ .../mutationobserver/mutationobserver/index.html | 101 +++++++++++++++++++ .../web/api/mutationobserver/observe/index.html | 110 +++++++++++++++++++++ .../api/mutationobserver/takerecords/index.html | 81 +++++++++++++++ 5 files changed, 476 insertions(+) create mode 100644 files/zh-cn/web/api/mutationobserver/disconnect/index.html create mode 100644 files/zh-cn/web/api/mutationobserver/index.html create mode 100644 files/zh-cn/web/api/mutationobserver/mutationobserver/index.html create mode 100644 files/zh-cn/web/api/mutationobserver/observe/index.html create mode 100644 files/zh-cn/web/api/mutationobserver/takerecords/index.html (limited to 'files/zh-cn/web/api/mutationobserver') diff --git a/files/zh-cn/web/api/mutationobserver/disconnect/index.html b/files/zh-cn/web/api/mutationobserver/disconnect/index.html new file mode 100644 index 0000000000..7de675ca81 --- /dev/null +++ b/files/zh-cn/web/api/mutationobserver/disconnect/index.html @@ -0,0 +1,74 @@ +--- +title: MutationObserver.disconnect() +slug: Web/API/MutationObserver/disconnect +translation_of: Web/API/MutationObserver/disconnect +--- +
{{APIRef("DOM WHATWG")}}
+ +

{{domxref("MutationObserver")}} 的 disconnect() 方法告诉观察者停止观察变动。 可以通过调用其{{domxref("MutationObserver.observe", "observe()")}}方法来重用观察者。

+ + + +

语法

+ +
mutationObserver.disconnect()
+
+ +

参数

+ +

无。

+ +

返回值

+ +

undefined.

+ +
+

注意: 所有已经检测到但是尚未向观察者报告的变动都会被丢弃。

+
+ +

使用说明

+ +

如果被观察的元素被从DOM中移除，然后被浏览器的垃圾回收机制释放，此MutationObserver将同样被删除。

+ +

示例

+ +

下面的示例创建了一个观察者，接着与之断开连接，让它可以重复使用。

+ +
var targetNode = document.querySelector("#someElement");
+var observerOptions = {
+  childList: true,
+  attributes: true
+}
+
+var observer = new MutationObserver(callback);
+observer.observe(targetNode, observerOptions);
+
+/* some time later... */
+
+observer.disconnect();
+ +

规范

+ + + + + + + + + + + + + + + + +
规范状态批注
{{SpecName('DOM WHATWG', '#dom-mutationobserver-disconnect', 'MutationObserver.disconnect()')}}{{ Spec2('DOM WHATWG') }} 
+ +

浏览器兼容性

+ + + +

{{Compat("api.MutationObserver.disconnect")}}

diff --git a/files/zh-cn/web/api/mutationobserver/index.html b/files/zh-cn/web/api/mutationobserver/index.html new file mode 100644 index 0000000000..21cd5d2ffc --- /dev/null +++ b/files/zh-cn/web/api/mutationobserver/index.html @@ -0,0 +1,110 @@ +--- +title: MutationObserver +slug: Web/API/MutationObserver +tags: + - API + - Advanced + - DOM + - DOM Reference + - MutationObserver + - requestAnimationFrame + - resize +translation_of: Web/API/MutationObserver +--- +

{{APIRef("DOM WHATWG")}}

+ +

{{domxref("MutationObserver")}}接口提供了监视对DOM树所做更改的能力。它被设计为旧的Mutation Events功能的替代品，该功能是DOM3 Events规范的一部分。

+ +

构造函数

+ +
+
{{domxref("MutationObserver.MutationObserver", "MutationObserver()")}}
+
创建并返回一个新的 MutationObserver 它会在指定的DOM发生变化时被调用。
+
+ +

方法

+ +
+
{{domxref("MutationObserver.disconnect", "disconnect()")}}
+
阻止 MutationObserver 实例继续接收的通知，直到再次调用其{{domxref("MutationObserver.observe", "observe()")}}方法，该观察者对象包含的回调函数都不会再被调用。
+
{{domxref("MutationObserver.observe", "observe()")}}
+
配置MutationObserver在DOM更改匹配给定选项时，通过其回调函数开始接收通知。
+
{{domxref("MutationObserver.takeRecords", "takeRecords()")}}
+
从MutationObserver的通知队列中删除所有待处理的通知，并将它们返回到{{domxref("MutationRecord")}}对象的新{{jsxref("Array")}}中。
+
+ +

Mutation Observer & customize resize event listener & demo

+ +

https://codepen.io/webgeeker/full/YjrZgg/

+ +

示例

+ +

以下示例改编自这篇博客。

+ +
// 选择需要观察变动的节点
+const targetNode = document.getElementById('some-id');
+
+// 观察器的配置（需要观察什么变动）
+const config = { attributes: true, childList: true, subtree: true };
+
+// 当观察到变动时执行的回调函数
+const callback = function(mutationsList, observer) {
+    // Use traditional 'for loops' for IE 11
+    for(let mutation of mutationsList) {
+        if (mutation.type === 'childList') {
+            console.log('A child node has been added or removed.');
+        }
+        else if (mutation.type === 'attributes') {
+            console.log('The ' + mutation.attributeName + ' attribute was modified.');
+        }
+    }
+};
+
+// 创建一个观察器实例并传入回调函数
+const observer = new MutationObserver(callback);
+
+// 以上述配置开始观察目标节点
+observer.observe(targetNode, config);
+
+// 之后，可停止观察
+observer.disconnect();
+
+ + + +

规范

+ + + + + + + + + + + + + + + + +
规范状态注释
{{SpecName('DOM WHATWG', '#mutationobserver', 'MutationObserver')}}{{ Spec2('DOM WHATWG') }}
+ +

浏览器兼容

+ + + +

{{Compat("api.MutationObserver")}}

+ +

参见

+ + diff --git a/files/zh-cn/web/api/mutationobserver/mutationobserver/index.html b/files/zh-cn/web/api/mutationobserver/mutationobserver/index.html new file mode 100644 index 0000000000..efa1d1a8f0 --- /dev/null +++ b/files/zh-cn/web/api/mutationobserver/mutationobserver/index.html @@ -0,0 +1,101 @@ +--- +title: MutationObserver.MutationObserver() +slug: Web/API/MutationObserver/MutationObserver +tags: + - API + - Constructor + - DOM + - MutationObserver + - 参考 + - 构造器 +translation_of: Web/API/MutationObserver/MutationObserver +--- +
{{APIRef("DOM WHATWG")}}
+ +

DOM 规范中的 MutationObserver() 构造函数——是 {{domxref("MutationObserver")}} 接口内容的一部分——创建并返回一个新的观察器，它会在触发指定 DOM 事件时，调用指定的回调函数。MutationObserver 对 DOM 的观察不会立即启动；而必须先调用 {{domxref("MutationObserver.observe", "observe()")}} 方法来确定，要监听哪一部分的 DOM 以及要响应哪些更改。

+ +

语法

+ +
var observer = new MutationObserver(callback);
+ +

参数

+ +
+
  callback
+
一个回调函数，每当被指定的节点或子树以及配置项有Dom变动时会被调用。回调函数拥有两个参数：一个是描述所有被触发改动的 {{domxref("MutationRecord")}} 对象数组，另一个是调用该函数的MutationObserver 对象。参见下方的{{anch("Example", "示例")}}了解更多细节  
+
+ +

返回值

+ +

一个新的、包含监听 DOM 变化回调函数的 {{domxref("MutationObserver")}} 对象。

+ +

示例

+ +

这个例子简单地创建了一个新的 MutationObserver ，监视一个节点及其全部子节点树的添加、移除元素，以及任何属性变化的事件。

+ +

回调函数

+ +
function callback(mutationList, observer) {
+  mutationList.forEach((mutation) => {
+    switch(mutation.type) {
+      case 'childList':
+        /* 从树上添加或移除一个或更多的子节点；参见 mutation.addedNodes 与
+           mutation.removedNodes */
+        break;
+      case 'attributes':
+        /* mutation.target 中某节点的一个属性值被更改；该属性名称在 mutation.attributeName 中，
+           该属性之前的值为 mutation.oldValue */
+        break;
+    }
+  });
+}
+
+ +

调用 {{domxref("MutationObserver.observe", "observe()")}} 即可开始观察 DOM。当观察者 observer 发现匹配观察请求中指定的配置项的更改时，callback() 方法便会被调用。

+ +

使用 {{domxref("MutationRecord.type", "mutation.type")}} 获取发生的变动类别（无论是子节点的变动，还是节点属性的变动）。

+ +

创建并使用 observer

+ +

使用以下代码设置一个观察进程。

+ +
var targetNode = document.querySelector("#someElement");
+var observerOptions = {
+  childList: true,  // 观察目标子节点的变化，是否有添加或者删除
+  attributes: true, // 观察属性变动
+  subtree: true     // 观察后代节点，默认为 false
+}
+
+var observer = new MutationObserver(callback);
+observer.observe(targetNode, observerOptions);
+ +

使用 ID someElement 来获取目标节点树。 observerOptions 中设定了观察者的选项，通过设定 childList 和 attributes 为 true 来获取所需信息。

+ +

当 observer 实例化时，指定 callback() 函数。之后指定目标节点与记录选项，我们开始观察使用 observe() 指定的 DOM 节点。

+ +

从现在开始直到调用 {{domxref("MutationObserver.disconnect", "disconnect()")}} ，每次以 targetNode 为根节点的 DOM 树添加或移除元素时，以及这些元素的任意属性改变时，callback() 都会被调用。

+ +

规范

+ + + + + + + + + + + + + + + + +
规范状态说明
{{SpecName('DOM WHATWG', '#dom-mutationobserver-mutationobserver', 'MutationObserver()')}}{{ Spec2('DOM WHATWG') }}
+ +

浏览器兼容性

+ + + +

{{Compat("api.MutationObserver.MutationObserver")}}

diff --git a/files/zh-cn/web/api/mutationobserver/observe/index.html b/files/zh-cn/web/api/mutationobserver/observe/index.html new file mode 100644 index 0000000000..5c6f18ba94 --- /dev/null +++ b/files/zh-cn/web/api/mutationobserver/observe/index.html @@ -0,0 +1,110 @@ +--- +title: MutationObserver.observe() +slug: Web/API/MutationObserver/observe +tags: + - API + - DOM + - MutationObserver + - Node + - 参考 + - 变化 + - 方法 +translation_of: Web/API/MutationObserver/observe +--- +
{{APIRef("DOM WHATWG")}}
+ +

{{domxref("MutationObserver")}}的 observe() 方法配置了 MutationObserver 对象的回调方法以开始接收与给定选项匹配的DOM变化的通知。根据配置，观察者会观察 DOM 树中的单个 {{domxref("Node")}}，也可能会观察被指定节点的部分或者所有的子孙节点。

+ +

要停止 MutationObserver（以便不再触发它的回调方法），需要调用{{domxref("MutationObserver.disconnect()")}}方法。

+ +

语法

+ +
mutationObserver.observe(target[, options])
+
+ +

参数

+ +
+
target
+
DOM树中的一个要观察变化的DOM {{domxref("Node")}} (可能是一个{{domxref("Element")}}) , 或者是被观察的子节点树的根节点。
+
options {{optional_inline}}
+
一个可选的{{domxref("MutationObserverInit")}} 对象，此对象的配置项描述了DOM的哪些变化应该提供给当前观察者的callback。
+
+ +

返回值

+ +

undefined。

+ +

异常

+ +
+
TypeError
+
以下任一情况都会抛出异常: +
    +
  • 配置选项使得实际上不会监视任何内容（例如，如果 {{domxref("MutationObserverInit.childList")}}，{{domxref("MutationObserverInit.attributes")}} 和 {{domxref("MutationObserverInit.characterData")}} 都为 false）。
    • +
  • attributes 选项为 false（表示不监视属性更改）但是attributeOldValue 为 true 并且/或者 attributeFilter 配置存在。
    • +
  • {{domxref("MutaitonObserverInit.characterDataOldValue", "characterDataOldValue")}} 选项为 true 但是 {{domxref("MutationObserverInit.characterData")}} 为 false（表示不跟踪字符更改）。
    • +
+
+
+ +

使用说明

+ +

复用 MutationObserver

+ +

你可以多次调用同一个 MutationObserver 对象的 observe() 方法，来观察 DOM 树中不同部分的变化，和/或不同类型的变化。有一些需要注意的注意事项：

+ + + +

当节点断开连接时继续观察节点

+ +

MutationObserver 旨在让您能够随着时间的推移观察所需的节点集，即使这些节点之间的直接连接被切断。如果你开始观察节点的子树，并且该子树的一部分被分离并移动到DOM中的其他位置，你将继续观察分离的节点段，接收与节点从原始子树分离之前相同的回调。

+ +

换句话说，在你收到有关节点从被观察子树中拆分的通知之前，你将收到有关该拆分子树及其节点的更改的通知。这可以防止你丢失在切断连接之后以及在你有机会专门开始观察已移动的节点或子树之前发生的变化。

+ +

这意味着理论上如果你跟踪描述发生的变化的{{domxref("MutationRecord")}}对象，你就可以“撤销”这些改动，将DOM恢复到初始状态。

+ +

示例

+ +

在此例子中，将为你演示如何在实例 {{domxref("MutationObserver")}} 中调用observe() 方法，一旦设置后，会传给他一个目标元素和一个 {{domxref("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});
+ +

规范

+ + + + + + + + + + + + + + + + +
规范状态备注
{{SpecName('DOM WHATWG', '#dom-mutationobserver-observe', 'MutationObserver.observe()')}}{{ Spec2('DOM WHATWG') }}
+ +

浏览器兼容性

+ + + +

{{Compat("api.MutationObserver.observe")}}

diff --git a/files/zh-cn/web/api/mutationobserver/takerecords/index.html b/files/zh-cn/web/api/mutationobserver/takerecords/index.html new file mode 100644 index 0000000000..b6ad1c65fc --- /dev/null +++ b/files/zh-cn/web/api/mutationobserver/takerecords/index.html @@ -0,0 +1,81 @@ +--- +title: MutationObserver.takeRecords() +slug: Web/API/MutationObserver/takeRecords +translation_of: Web/API/MutationObserver/takeRecords +--- +
{{APIRef("DOM WHATWG")}}
+ +

{{domxref("MutationObserver")}} 的 takeRecords() 方法返回已检测到但尚未由观察者的回调函数处理的所有匹配DOM更改的列表，使变更队列保持为空。 此方法最常见的使用场景是在断开观察者之前立即获取所有未处理的更改记录，以便在停止观察者时可以处理任何未处理的更改。

+ + + +

语法

+ +
mutationRecords = mutationObserver.takeRecords()
+
+ +

参数

+ +

无。

+ +

返回值

+ +

返回一个{{domxref("MutationRecord")}} 对象列表，每个对象都描述了应用于DOM树某部分的一次改动。

+ +
+

注意: 调用takeRecords()后，已发生但未传递给回调的变更队列将保留为空。

+
+ +

示例

+ +

下面的示例展示了在断开观察者之前如何通过调用takeRecords()来处理任何未传递的{{domxref("MutationRecord")}}。

+ +
var targetNode = document.querySelector("#someElement");
+var observerOptions = {
+  childList: true,
+  attributes: true
+}
+
+var observer = new MutationObserver(callback);
+observer.observe(targetNode, observerOptions);
+
+/* ...later, when it's time to stop observing... */
+
+/* handle any still-pending mutations */
+
+var mutations = observer.takeRecords();
+
+if (mutations) {
+  callback(mutations);
+}
+
+observer.disconnect();
+
+ +

代码中第12-17行抓取了所有未处理的变更记录，然后调用回调，并将变更记录列表传递给回调，以保证所有变更记录都被处理。这是在调用{{domxref("MutationObserver.disconnect", "disconnect()")}}之前完成的，以便停止观察DOM。 

+ +

规范

+ + + + + + + + + + + + + + + + +
规范状态批注
{{SpecName('DOM WHATWG', '#dom-mutationobserver-takerecords', 'MutationObserver.takeRecords()')}}{{ Spec2('DOM WHATWG') }} 
+ +

浏览器兼容性

+ + + +

{{Compat("api.MutationObserver.takeRecords")}}

-- cgit v1.2.3-54-g00ecf