CKTIS / JavaScript
Опции на MutationObserver: видове промени, поддърво, филтър и предишни стойности
Настрой `observe()` да следи промени в дъщерни възли, атрибути или символни данни. Избери обхвата на наблюдението и кога записът да съдържа стойността отпреди промяната.
Версия: ECMAScript 2024 and the current web platform; runtime support varies
Синтаксис
const observer = new MutationObserver((records, observer) => {
for (const record of records) {
// Read record.type, record.target, or record.oldValue.
}
});
observer.observe(target, {
childList: true,
attributes: true,
characterData: true,
subtree: true,
attributeFilter: ["data-state"],
attributeOldValue: true,
characterDataOldValue: true,
});new MutationObserver(callback) създава наблюдател; observer.observe(target, options) започва наблюдение на DOM възел. Функцията за обратно извикване получава масив от обекти MutationRecord и наблюдателя. Това е DOM API на уеб платформата, а не част от ECMAScript 2024; наличността зависи от средата за изпълнение.
childList отчита добавяне или премахване на преки дъщерни възли на наблюдавания възел (addedNodes, removedNodes). attributes отчита добавяне, промяна или премахване на атрибути на елемент. characterData отчита редакции на съществуващ възел CharacterData, например промяна на text.data. Задаването на textContent на елемент заменя дъщерните му възли. Ако списъкът им се промени, промяната се отчита като childList, а не като characterData. subtree: true разширява наблюдението на избраните видове промени и към потомците; по подразбиране се наблюдава само target.
attributeFilter изброява локални имена на атрибути, а не CSS селектори. При зададен филтър съвпадат само изброените атрибути без пространство от имена; без филтър се вземат предвид всички атрибути. attributeOldValue: true и characterDataOldValue: true запазват стойността отпреди съответната промяна в свойството само за четене record.oldValue. Няма опция oldValue или поле newValue. oldValue е null при childList, когато запазването на предишната стойност не е заявено или когато атрибутът не е съществувал преди промяната.
childList по подразбиране е false. Ако attributes е пропуснато, става true при зададено attributeFilter или attributeOldValue; ако characterData е пропуснато, става true при зададено characterDataOldValue. Достатъчно е опцията за предишна стойност да присъства, дори със стойност false. В останалите случаи и двата вида са изключени по подразбиране. observe() хвърля TypeError, ако никой вид не е включен, ако attributes: false е съчетано с филтър или с attributeOldValue: true, или ако characterData: false е съчетано с characterDataOldValue: true.
Записите се подават на групи към функцията за обратно извикване в микрозадача, а не по време на самата промяна в DOM. При subtree: true временните регистрации позволяват поддървото на отделен потомък да остане под наблюдение. Микрозадачата за известяване премахва тези регистрации, когато обработва наблюдателя, преди евентуалното извикване на обратната функция. Премахването на регистрациите не изисква да бъде доставен запис за премахването на възела: childList може да е изключено или takeRecords() вече да е изпразнил опашката. disconnect() спира наблюдението и отхвърля чакащите записи. Ако са ти нужни, първо ги вземи с takeRecords(), което изпразва опашката.
Примери
<!doctype html>
<meta charset="utf-8">
<title>MutationObserver options</title>
<script>
const root = document.createElement("div");
const item = document.createElement("span");
const text = document.createTextNode("before");
item.setAttribute("data-state", "idle");
item.append(text);
root.append(item);
const observer = new MutationObserver((records, self) => {
for (const record of records) {
console.log(JSON.stringify([record.type, record.attributeName, record.oldValue]));
}
self.disconnect();
});
observer.observe(root, {
childList: true,
subtree: true,
attributeFilter: ["data-state"],
attributeOldValue: true,
characterDataOldValue: true,
});
item.setAttribute("data-state", "ready");
item.setAttribute("title", "ignored");
text.data = "after";
item.append(document.createElement("em"));
</script>Резултат
["attributes","data-state","idle"] ["characterData",null,"before"] ["childList",null,null]
Запази целия пример като файл с разширение `.html` и го отвори в браузър. Отвори конзолата за разработчици и презареди страницата. Възлите не се добавят към страницата. Филтърът изключва `title`, а опциите за предишни стойности включват пропуснатите `attributes` и `characterData`. Функцията за обратно извикване извежда три записа по реда на промените, след което спира наблюдението.
Свързани уроци
- JavaScript · Урок 31 · Средно · Версия: 3
Източници
- MutationObserver: observe() method
- MutationObserver: MutationObserver() constructor
- MutationRecord
- MutationRecord: oldValue property
- Node: textContent property
- Using microtasks in JavaScript with queueMicrotask()
- HTML Standard — Event loops
- MutationObserver: disconnect() method
- MutationObserver: takeRecords() method