MutationObserver

Перевод не завершен. Пожалуйста, помогите перевести эту статью с английского.

MutationObserver предоставляет возможность получать уведомления об изменении определённых DOM-элементов.  MutationObserver является заменой Mutation Events, определённой в спецификации DOM3 Events.

Constructor

MutationObserver()

Конструктор, служит для создания новых наблюдателей за изменениями DOM.

new MutationObserver(
  function callback
);
Parameters
callback
Вызывается при каждом изменении DOM-элемента. Observer вызывает данную функцию с двумя аргументами. Первым аргументом является массив объектов MutationRecord, Вторым аргументом является экземпляр MutationObserver.

Instance methods

void observe( Node target, MutationObserverInit options );
void disconnect();
Array takeRecords();

Note: Не стоит ассоциировать  Node target с NodeJS.

observe()

Подписывает экземпляр MutationObserver на получение уведомлений о манипуляциях с DOM-элементом.

void observe(
  Node target,
  MutationObserverInit options
);
Parameters
target
Элемент дерева DOM, изменения которого необходимо отслеживать.
options
Объект MutationObserverInit, указывающий о каких изменениях DOM-элемента должны поступать уведомления.
NOTE: Добавление observer на элемент, по сути, то же самое, что и добавление addEventListener, если вы подписываете на изменения несколько раз, это не сыграет роли. Это означает, что если вы подписываетесь на изменения дважды, функция callback не будет вызвана второй раз, и у вас не будет необходимости вызывать disconnect() несколько раз. Другими словами, если один экземпляр MutationObserver уже подписан на изменения элемента, то при попытке подписать его на изменения того же элемента второй раз ничего не произойдет. Однако, если функция callback будет изменена, это добавит еще один observer к объекту.

disconnect()

Прекращает получение уведомлений об изменении DOM-элемента экземпляром MutationObserver, до того момента пока не будет вызван метод observe().

void disconnect();

takeRecords()

Возвращает текущую очередь экземпляра MutationObserver, затем очищает её.

Array takeRecords();
Return value

Возвращает массив из MutationRecord.

MutationObserverInit

MutationObserverInit объект, который может содержать следующие свойства:

NOTE: Так или иначе необходимо установить true для одного из следующих свойств: childList, attributes, characterData. В противном случае будет вызвана ошибка  "An invalid or illegal string was specified"
Property Description
childList

true, если необходимо наблюдать за добавлением или удалением дочерних элементов (Включая текстовые узлы (text nodes))

attributes

true, если необходимо наблюдать за изменениями атрибутов целевого элемента.

characterData

true, если необходимо наблюдать за изменениями значения текстового содержимого целевого узла (текстовых узлов дочернего элемента).

subtree

true, если необходимо наблюдать за потомками целевого элемента. 

attributeOldValue

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

characterDataOldValue

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

attributeFilter

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

Example usage

Приведённый ниже пример взят из этого блога.

// выбираем целевой элемент
var target = document.getElementById('some-id');
 
// создаём экземпляр MutationObserver
var observer = new MutationObserver(function(mutations) {
  mutations.forEach(function(mutation) {
    console.log(mutation.type);
  });    
});
 
// конфигурация нашего observer:
var config = { attributes: true, childList: true, characterData: true };
 
// передаём в качестве аргументов целевой элемент и его конфигурацию
observer.observe(target, config);
 
// позже можно остановить наблюдение
observer.disconnect();

Additional reading

Specifications

Specification Status Comment
DOM
Определение 'MutationObserver' в этой спецификации.
Живой стандарт  
DOM4
Определение 'MutationObserver' в этой спецификации.
Рекомендация  

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support 18 -webkit
26
14 (14) 11 15 6.0 -webkit
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support 4.4 18 -webkit
26
14.0 (14) 11 (8.1) 15 6 -webkit
7

Метки документа и участники

 Внесли вклад в эту страницу: torbasow, Allgoll
 Обновлялась последний раз: torbasow,