База знанияИзпитен център
BGБългарски
Избери език13

CKTIS / JavaScript

MutationObserver: observe(), disconnect() и takeRecords()

Наблюдавайте избрани промени в DOM, вземайте чакащите записи, без да чакате обратното извикване, и решете дали да ги запазите при спиране на наблюдението.

Версия: ECMAScript 2024 and the current web platform; runtime support varies

Синтаксис

const observer = new MutationObserver(callback);
observer.observe(target, options);
const records = observer.takeRecords();
observer.disconnect();

new MutationObserver(callback) създава наблюдател, но не започва наблюдението. observe(target, options), disconnect() и takeRecords() са методи на екземпляра, а не статични методи. Съответстващите промени влизат в опашка. Микрозадача за уведомяване ги предава заедно на callback(records, observer), вместо да извиква функцията синхронно при всяка промяна.

observe(target, options) регистрира възел от DOM (Node) и връща undefined. Следващите извиквания могат да добавят други цели или да променят настройките за същата цел. childList следи за добавяне и премахване на преки деца, attributes следи промените на атрибути, а characterData — промените в данните на възел, например съдържанието на текстов възел. subtree: true прилага същите правила и към потомците. Промени в премахнат клон все още могат да попаднат в опашката преди следващата микрозадача за уведомяване.

attributeFilter ограничава имената на наблюдаваните атрибути. attributeOldValue: true и characterDataOldValue: true запазват предишната стойност в oldValue. Ако attributes е пропуснато, задаването на attributeFilter или attributeOldValue включва наблюдението на атрибути. Задаването на characterDataOldValue по същия начин включва characterData, ако то е пропуснато. observe() хвърля TypeError, ако няма включен вид промени, ако attributes: false е съчетано с филтър или с attributeOldValue: true, или ако characterData: false е съчетано с characterDataOldValue: true.

takeRecords() връща синхронно масив от чакащи обекти MutationRecord ([], ако опашката е празна) и изпразва опашката. Методът не спира наблюдението и не задейства обратното извикване: сами обработвате върнатите записи. disconnect() връща undefined, спира наблюдението на всички цели на този екземпляр и изхвърля непредадените записи. За да ги запазите, извикайте takeRecords() непосредствено преди disconnect(). Можете да използвате наблюдателя отново с ново извикване на observe().

Това е DOM API на уеб платформата, а не част от ECMAScript 2024. Наличността зависи от средата за изпълнение. Наблюдателят не дава достъп до иначе недостъпни възли, например в iframe с различен произход.

Примери

<!doctype html>
<meta charset="utf-8">
<title>MutationObserver example</title>
<script>
  const target = document.createElement('div');
  const options = { attributes: true, attributeFilter: ['data-state'] };
  const observer = new MutationObserver((records, currentObserver) => {
    console.log(`callback: ${records.length} ${records[0].attributeName}`);
    currentObserver.disconnect();
  });

  observer.observe(target, options);
  target.setAttribute('data-state', 'first');
  const [record] = observer.takeRecords();
  console.log(`taken: ${record.type} ${record.attributeName}`);

  target.setAttribute('data-state', 'discarded');
  observer.disconnect();
  target.setAttribute('data-state', 'unobserved');
  console.log(`remaining: ${observer.takeRecords().length}`);

  observer.observe(target, options);
  target.setAttribute('data-state', 'delivered');
</script>

Резултат

taken: attributes data-state
remaining: 0
callback: 1 data-state

Запазете целия пример като HTML файл, отворете го в браузър и проверете изхода в конзолата за разработчици. Елементът не се добавя към страницата. `takeRecords()` взема първия запис, `disconnect()` изхвърля втория, а промяната по време на прекъсването не се записва. Само промяната след възобновяването се предава на функцията за обратно извикване.

Свързани уроци

  • JavaScript · Урок 31 · Средно · Версия: 3

Източници