DOM | Интерфейс MutationObserver

IDL

[Exposed=Window]
interface MutationObserver {
   constructor(MutationCallback callback);

   undefined observe(Node target, optional MutationObserverInit options = {});
   undefined disconnect();
   sequence<MutationRecord> takeRecords();
};

callback MutationCallback = undefined (sequence<MutationRecord> mutations, MutationObserver observer);

dictionary MutationObserverInit {
   boolean childList = false;
   boolean attributes;
   boolean characterData;
   boolean subtree = false;
   boolean attributeOldValue;
   boolean characterDataOldValue;
   sequence<DOMString> attributeFilter;
};

Объект MutationObserver может использоваться для наблюдения за мутациями дерева узлов.

С каждым объектом MutationObserver связаны следующие концепции:

«Обратный вызов» (callback), установленный при создании.
«Список узлов» (node list) (список узлов), который изначально пуст.
«Очередь записей» (record queue) (очередь из нуля или более объектов MutationRecord), которая изначально пуста.

Для веб-разработчиков (не нормативно)

observer = new MutationObserver(callback)

Создает объект MutationObserver и устанавливает его обратный вызов в callback. Обратный вызов callback вызывается со списком объектов MutationRecord в качестве первого аргумента и созданного объекта MutationObserver в качестве второго аргумента. Он вызывается после мутации узлов, зарегистрированных методом наблюдения observe().

observer . observe(target, options)

Дает указание пользовательскому агенту наблюдать за заданной целью target (узел) и сообщать о любых мутациях на основе критериев, заданных параметрами options (объектом).

Аргумент options позволяет устанавливать параметры наблюдения за мутациями через участников объекта. Вот участники объекта, которые можно использовать:

childList

Установите значение true, если нужно наблюдать за мутациями детей цели target.

attributes

Установите значение true, если необходимо наблюдать за мутациями атрибутов цели target. Может быть опущено, если указан attributeOldValue или attributeFilter.

characterData

Установите значение true, если необходимо наблюдать мутации в данных цели target. Может быть опущено, если указан characterDataOldValue.

subtree

Установите значение true, если необходимо наблюдать мутации не только для цели target, но и для ее потомков.

attributeOldValue

Установите значение true, если атрибуты attributes истинны или опущены, а значение атрибута цели target перед изменением необходимо записать.

characterDataOldValue

Установите значение true, если для characterData задано значение true или опущено, а данные цели target до мутации необходимо записать.

attributeFilter

Установите в список локальных имен атрибутов (без пространства имен), если не все атрибуты мутаций необходимо соблюдать и attributes истинны или опущены.

observer . disconnect()

Останавливает observer от наблюдения за любыми мутациями. До тех пор, пока снова не будет использован метод наблюдения observe(), обратный вызов observer не будет вызываться.

observer . takeRecords()

Очищает очередь записей и возвращает то, что там было.

При вызове конструктора MutationObserver(callback) необходимо выполнить следующие действия:

1. Пусть mo будет новым объектом MutationObserver, обратным вызовом которого является callback.
2. Добавить mo к наблюдателям мутаций соответствующего агента mo.
3. Вернуть mo.

При вызове метода наблюдения observe(target, options) должны выполняться следующие шаги:

1. Если параметр attributeOldValue или attributeFilter options присутствует, а параметр «attributes» options опущен, то установите для параметра «attributes» options значение true.
2. Если параметр characterDataOldValue options присутствует, а параметр characterData options опущен, установите для параметра characterData options значение true.
3. Если ни один из параметров options - childList, attributes и characterData не является истинным, то выдает ошибку TypeError.
4. Если для параметра options attributeOldValue установлено значение true, а для attributes options установлено значение false, генерировать ошибку TypeError.
5. Если параметр options attributeFilter присутствует, а attributes options имеют значение false, генерировать ошибку TypeError.
6. Если параметр options characterDataOldValue имеет значение true, а параметр options characterData - false, то выдает ошибку TypeError.
7. Для каждой зарегистрированной registered из списка зарегистрированных наблюдателей цели target, если наблюдатель registered это this:
1. Для каждого узла node из списка узлов этого this удалите всех временных зарегистрированных наблюдателей, источник которых является registered из списка зарегистрированных наблюдателей узла node.
2. Установите параметры registered на options.
8. Иначе:
1. Добавьте нового зарегистрированного наблюдателя, чей наблюдатель это this, а опции - это options в список зарегистрированных наблюдателей цели target.
2. Добавить цель target в список узлов этого this.

При вызове метода disconnect() необходимо выполнить следующие действия:

1. Для каждого узла node в списке узлов этого this, удалите любого зарегистрированного наблюдателя из списка зарегистрированных наблюдателей узла node, для которого this является наблюдателем.
2. Очистите очередь записей этого this.

При вызове метода takeRecords() необходимо выполнить следующие действия:

1. Пусть записи records будут клоном очереди записей этого this.
2. Очистите очередь записей этого this.
3. Верните records

Ссылки

DOM стандарт — https://efim360.ru/dom/

Читайте перевод полной версии стандарта «объектной модели документа», чтобы ознакомиться со всеми концепциями и интерфейсами.

DOM — Living Standard — https://dom.spec.whatwg.org

Читайте официальную документацию живого стандарта «объектной модели документа», чтобы быть в курсе последних изменений.