CKTIS / JavaScript
MutationObserver — наблюдение на промени в DOM
MutationObserver записва избрани промени в DOM и асинхронно предава записите на функция за обратно извикване. Научете как observe() настройва наблюдението, takeRecords() изпразва опашката, а disconnect() спира наблюдението.
Версия: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Синтаксис
const observer = new MutationObserver((records, observer) => { /* handle records */ });
observer.observe(target, options);
const pending = observer.takeRecords();
observer.disconnect();MutationObserver е API от стандарта DOM, а не част от самия ECMAScript. Функцията за обратно извикване получава масив от обекти MutationRecord и наблюдателя. Уведомлението се поставя на опашка като микрозадача и не се доставя синхронно по време на промяна; едно извикване може да съдържа няколко записа. Наличието на Node 24 в хранилище не доказва, че този API на браузъра е достъпен.
MutationObserver.observe, извикан като observer.observe(target, options), избира възел и типове мутации: childList следи добавянето и премахването на деца, attributes следи атрибутите, а characterData — данните на текстови и подобни възли. subtree: true включва потомците. След прилагането на стойностите по подразбиране трябва да е активиран поне един тип; в противен случай се хвърля TypeError. attributeFilter ограничава имената на атрибутите; attributeOldValue и characterDataOldValue изискват предишните стойности. Опциите за атрибути или данни могат неявно да активират съответния тип наблюдение, но изрично противоречащите си настройки водят до TypeError.
MutationObserver.takeRecords, извикан като observer.takeRecords(), синхронно връща чакащите записи и изпразва опашката, без да извиква функцията за обратно извикване или да спира наблюдението. MutationObserver.disconnect, извикан като observer.disconnect(), спира всички наблюдения на този обект и изхвърля чакащите записи. Ако са ви нужни, вземете ги предварително. Обектът може да бъде стартиран отново с observe().
Примерът наблюдава отделен елемент, взема записа му преди доставянето на уведомлението и спира наблюдението. oldValue е null, защото атрибутът не е съществувал преди това. Ограничете обхвата на наблюдение; мутациите, извършени от функцията за обратно извикване, могат да предизвикат нови уведомления.
Примери
{
const target = document.createElement('div');
const observer = new MutationObserver((records) => {
console.log('callback:', records.length);
});
observer.observe(target, {
attributes: true,
attributeFilter: ['data-state'],
attributeOldValue: true
});
target.setAttribute('data-state', 'ready');
const records = observer.takeRecords();
console.log(JSON.stringify(records.map((record) => ({
type: record.type,
attributeName: record.attributeName,
oldValue: record.oldValue
}))));
observer.disconnect();
target.setAttribute('data-state', 'done');
console.log(observer.takeRecords().length);
}Резултат
[{"type":"attributes","attributeName":"data-state","oldValue":null}]
0Показаният код и заявеният резултат са проверени в изолирана среда по метода, записан в доказателството за проверка на тази точна версия.