MutationObserver: observe() Methode
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
Die MutationObserver
-Methode observe()
konfiguriert den MutationObserver
-Callback, um mit dem Empfang von Benachrichtigungen über Änderungen am DOM zu beginnen, die den angegebenen Optionen entsprechen.
Abhängig von der Konfiguration kann der Beobachter einen einzelnen Node
im DOM-Baum oder diesen Knoten sowie einige oder alle seiner Nachkommen beobachten. Derselbe Knoten kann von mehreren Beobachtern überwacht werden, und derselbe MutationObserver
kann auf Änderungen in verschiedenen Teilen des DOM-Baums und/oder auf verschiedene Arten von Änderungen achten, indem er observe()
mehrmals auf demselben MutationObserver
aufruft.
Um den MutationObserver
zu stoppen (damit keiner seiner Callbacks mehr ausgelöst wird), rufen Sie MutationObserver.disconnect()
auf.
Syntax
observe(target, options)
Parameter
target
-
Ein DOM-
Node
(welches einElement
sein kann) im DOM-Baum, der auf Änderungen überwacht werden soll, oder der die Wurzel eines Teilbaums von Knoten sein soll, die überwacht werden sollen. options
-
Ein Objekt, das Optionen bietet, die beschreiben, welche DOM-Mutationen an den
callback
desmutationObserver
gemeldet werden sollen. Mindestens eines der FelderchildList
,attributes
und/odercharacterData
musstrue
sein, wennobserve()
aufgerufen wird. Andernfalls wird eineTypeError
-Ausnahme ausgelöst.Die Optionen sind wie folgt:
subtree
Optional-
Auf
true
gesetzt, um die Überwachung auf den gesamten vontarget
verwurzelten Teilbaum von Knoten auszudehnen. Alle anderen Eigenschaften werden dann auf alle Knoten im Teilbaum ausgeweitet, anstatt nur auf dentarget
-Knoten angewendet zu werden. Der Standardwert istfalse
. Beachten Sie, dass wenn ein Abkömmling vontarget
entfernt wird, Änderungen in diesem Teilbaum weiterhin beobachtet werden, bis die Benachrichtigung über die Entfernung selbst geliefert wurde. childList
Optional-
Auf
true
gesetzt, um den Zielknoten (und, fallssubtree
true
ist, seine Nachkommen) auf das Hinzufügen neuer Kinderknoten oder das Entfernen bestehender Kinderknoten zu überwachen. Der Standardwert istfalse
. attributes
Optional-
Auf
true
gesetzt, um Änderungen des Wertes der Attribute auf dem oder den überwachten Knoten zu beobachten. Der Standardwert isttrue
, wenn entwederattributeFilter
oderattributeOldValue
angegeben ist, andernfalls ist der Standardwertfalse
. attributeFilter
Optional-
Ein Array spezifischer Attributnamen, die überwacht werden sollen. Wenn diese Eigenschaft nicht enthalten ist, führen Änderungen an allen Attributen zu Mutationsbenachrichtigungen.
attributeOldValue
Optional-
Auf
true
gesetzt, um den vorherigen Wert eines Attributs aufzuzeichnen, das sich ändert, wenn auf dem oder den überwachten Knoten nach Attributänderungen gesucht wird. Siehe Überwachung von Attributwerten für ein Beispiel für die Beobachtung von Attributänderungen und die Aufzeichnung von Werten. Der Standardwert istfalse
. characterData
Optional-
Auf
true
gesetzt, um den angegebenen Zielknoten (und, fallssubtree
true
ist, seine Nachkommen) auf Änderungen der im oder den Knoten enthaltenen Zeichendaten zu überwachen. Der Standardwert isttrue
, wenncharacterDataOldValue
angegeben ist, andernfalls ist der Standardwertfalse
. characterDataOldValue
Optional-
Auf
true
gesetzt, um den vorherigen Wert des Textes eines Knotens aufzuzeichnen, wann immer sich der Text auf den überwachten Knoten ändert. Der Standardwert istfalse
.
Rückgabewert
Keiner (undefined
).
Ausnahmen
TypeError
-
Wird in einem der folgenden Umstände ausgelöst:
- Die
options
sind so konfiguriert, dass tatsächlich nichts überwacht wird. (Zum Beispiel, wennchildList
,attributes
undcharacterData
allefalse
sind.) - Der Wert von
options.attributes
istfalse
(was darauf hinweist, dass Attributänderungen nicht überwacht werden sollen), aberattributeOldValue
isttrue
und/oderattributeFilter
ist vorhanden. - Die
characterDataOldValue
-Option isttrue
, abercharacterData
istfalse
(was darauf hinweist, dass Zeichenänderungen nicht überwacht werden sollen).
- Die
Beispiele
Grundlegende Nutzung
In diesem Beispiel zeigen wir, wie man die Methode observe()
auf einer Instanz von MutationObserver
aufruft, nachdem sie eingerichtet wurde, indem man ihr ein Ziel-Element und ein options
-Objekt übergibt.
// create a new instance of `MutationObserver` named `observer`,
// passing it a callback function
const observer = new MutationObserver(() => {
console.log("callback that runs when observer is triggered");
});
// call `observe()`, passing it the element to observe, and the options object
observer.observe(document.querySelector("#element-to-observe"), {
subtree: true,
childList: true,
});
Entfernte Nachkommen bei Verwendung von subtree
Wenn Sie einen Knoten mit der subtree
-Option beobachten, erhalten Sie weiterhin Benachrichtigungen über Änderungen an den Nachkommen des Knotens, selbst nachdem ein Teil des Teilbaums entfernt wurde. Sobald jedoch die Benachrichtigung über die Entfernung geliefert wurde, werden weitere Änderungen am getrennten Teilbaum den Beobachter nicht mehr auslösen.
Dies verhindert, dass Sie Änderungen verpassen, die nach der Unterbrechung der Verbindung auftreten und bevor Sie die Gelegenheit haben, den verschobenen Knoten oder Teilbaum konkret auf Änderungen zu überwachen. Theoretisch bedeutet dies, dass, wenn Sie die MutationRecord
-Objekte im Auge behalten, die die aufgetretenen Änderungen beschreiben, Sie die Änderungen "rückgängig machen" und das DOM in seinen ursprünglichen Zustand zurückversetzen könnten.
<div id="target">
<div id="child"></div>
</div>
const target = document.getElementById("target");
const child = document.getElementById("child");
const observer = new MutationObserver((mutations) => {
mutations.forEach((mutation) => {
console.log(mutation.type, mutation.target.id, mutation.attributeName);
if (mutation.type === "childList" && mutation.target.id === "target") {
// After receiving the notification that the child was removed,
// further modifications to the detached subtree no longer trigger the observer.
child.setAttribute("data-bar", "");
}
});
});
observer.observe(target, {
attributes: true,
childList: true,
subtree: true,
});
target.removeChild(child);
// This change happens before the "childList target" notification is delivered,
// so it will also trigger the observer.
child.setAttribute("data-foo", "");
// Output:
// childList target null
// attributes child data-foo
// There is no "attributes child data-bar" notification.
Verwendung von attributeFilter
In diesem Beispiel wird ein Mutationsbeobachter eingerichtet, um Änderungen an den Attributen status
und username
in beliebigen Elementen innerhalb eines Teilbaums, der die Namen der Benutzer eines Chatraums anzeigt, zu beobachten. Dies ermöglicht es dem Code, beispielsweise Änderungen an den Spitznamen der Benutzer widerzuspiegeln oder sie als abwesend von der Tastatur (AFK) oder offline zu markieren.
function callback(mutationList) {
mutationList.forEach((mutation) => {
switch (mutation.type) {
case "attributes":
switch (mutation.attributeName) {
case "status":
userStatusChanged(mutation.target.username, mutation.target.status);
break;
case "username":
usernameChanged(mutation.oldValue, mutation.target.username);
break;
}
break;
}
});
}
const userListElement = document.querySelector("#user-list");
const observer = new MutationObserver(callback);
observer.observe(userListElement, {
attributeFilter: ["status", "username"],
attributeOldValue: true,
subtree: true,
});
Überwachung von Attributwerten
In diesem Beispiel beobachten wir ein Element auf Änderungen der Attributwerte und fügen eine Schaltfläche hinzu, die das dir
-Attribut des Elements zwischen "ltr"
und "rtl"
umschaltet. Im Callback des Beobachters protokollieren wir den alten Wert des Attributs.
HTML
<button id="toggle">Toggle direction</button><br />
<div id="container">
<input type="text" id="rhubarb" dir="ltr" value="Tofu" />
</div>
<pre id="output"></pre>
CSS
body {
background-color: paleturquoise;
}
button,
input,
pre {
margin: 0.5rem;
}
JavaScript
const toggle = document.querySelector("#toggle");
const rhubarb = document.querySelector("#rhubarb");
const observerTarget = document.querySelector("#container");
const output = document.querySelector("#output");
toggle.addEventListener("click", () => {
rhubarb.dir = rhubarb.dir === "ltr" ? "rtl" : "ltr";
});
const config = {
subtree: true,
attributeOldValue: true,
};
const callback = (mutationList) => {
for (const mutation of mutationList) {
if (mutation.type === "attributes") {
output.textContent = `The ${mutation.attributeName} attribute was modified from "${mutation.oldValue}".`;
}
}
};
const observer = new MutationObserver(callback);
observer.observe(observerTarget, config);
Ergebnis
Spezifikationen
Specification |
---|
DOM Standard # ref-for-dom-mutationobserver-observe② |
Browser-Kompatibilität
BCD tables only load in the browser