MutationObserver: метод observe()

Метод MutationObserver observe() настраивает MutationObserver коллбек для начала получения уведомлений о изменениях в DOM, которые соответствуют заданным параметрам.

В зависимости от конфигурации, наблюдатель может следить за одним Node в дереве DOM, или за этим узлом и некоторыми или всеми его дочерними узлами. Один и тот же узел может наблюдаться несколькими наблюдателями, и один и тот же MutationObserver может отслеживать изменения в разных частях дерева DOM и/или разных типах изменений, вызывая observe() несколько раз для того же MutationObserver.

Чтобы остановить MutationObserver (чтобы ни один из его коллбеков больше не срабатывал), вызовите MutationObserver.disconnect().

target

Узел DOM Node (который может быть Element) в дереве DOM, за изменениями которого нужно наблюдать, или узел, являющийся корнем поддерева узлов, за которыми нужно наблюдать.

options

Объект, предоставляющий параметры, которые описывают, какие мутации DOM должны быть сообщены mutationObserver's callback. Как минимум, один из childList, attributes, и/или characterData должен быть true при вызове observe(). В противном случае будет брошено исключение TypeError.

Параметры следующие:

subtree Необязательно

Установите в true чтобы расширить мониторинг на всё поддерево узлов, укорененное в target. Все остальные свойства затем расширяются на все узлы в поддереве вместо применения только к узлу target. Значение по умолчанию — false. Обратите внимание, что если дочерний узел target удаляется, изменения в этом поддереве дочерних узлов будут продолжать наблюдаться до тех пор, пока не будет доставлено уведомление об удалении.

childList Необязательно

Установите в true для мониторинга целевого узла (и, если subtree равен true, его потомков) для добавления новых дочерних узлов или удаления существующих дочерних узлов. Значение по умолчанию — false.

attributes Необязательно

Установите в true для отслеживания изменений значения атрибутов узла или узлов, за которыми ведется наблюдение. Значение по умолчанию — true если указан любой из attributeFilter или attributeOldValue, в противном случае значение по умолчанию — false.

attributeFilter Необязательно

Массив имен конкретных атрибутов, за которыми необходимо следить. Если это свойство не включено, изменения всех атрибутов вызывают уведомления о мутациях.

attributeOldValue Необязательно

Установите в true для записи предыдущего значения любого атрибута, который изменяется при мониторинге узла или узлов на предмет изменений атрибутов; см. Мониторинг значений атрибутов для примера наблюдения за изменениями атрибутов и записи значений. Значение по умолчанию — false.

characterData Необязательно

Установите в true для мониторинга указанного целевого узла (и, если subtree равен true, его потомков) на предмет изменений символьных данных, содержащихся в узле или узлах. Значение по умолчанию — true если указан characterDataOldValue, в противном случае значение по умолчанию — false.

characterDataOldValue Необязательно

Установите в true для записи предыдущего значения текста узла всякий раз, когда текст изменяется в наблюдаемых узлах. Значение по умолчанию — false.

Нет (undefined).

TypeError

Бросается в следующих обстоятельствах:

• options настроены таким образом, что ничего фактически не будет отслеживаться. (Например, если childList, attributes, и characterData все false.)
• Значение options.attributes равно false (указывает, что изменения атрибутов не должны отслеживаться), но attributeOldValue равно true и/или attributeFilter присутствует.
• Параметр characterDataOldValue равен true, но characterData равен false (указывает, что изменения символьных данных не должны отслеживаться).

В этом примере показано, как вызвать метод observe() на экземпляре MutationObserver, после его настройки, передав ему целевой элемент и объект options.

// create a new instance of `MutationObserver` named `observer`,
// passing it a callback function
const observer = new MutationObserver(() => {
  console.log("callback that runs when observer is triggered");
});

// call `observe()`, passing it the element to observe, and the options object
observer.observe(document.querySelector("#element-to-observe"), {
  subtree: true,
  childList: true,
});

Если вы наблюдаете за узлом с помощью параметра subtree, вы будете продолжать получать уведомления об изменениях в потомках узла, даже после удаления части поддерева. Однако после получения уведомления об удалении дальнейшие изменения в отделенном поддереве больше не будут вызывать наблюдателя.

Это предотвращает пропуск изменений, которые происходят после разрыва соединения и до того, как у вас будет возможность начать специально отслеживать перемещенный узел или поддерево на предмет изменений. Теоретически, это означает, что если вы отслеживаете объекты MutationRecord, описывающие происходящие изменения, вы должны иметь возможность "отменить" изменения, возвращая DOM к исходному состоянию.

<div id="target">
  <div id="child"></div>
</div>

const target = document.getElementById("target");
const child = document.getElementById("child");

const observer = new MutationObserver((mutations) => {
  mutations.forEach((mutation) => {
    console.log(mutation.type, mutation.target.id, mutation.attributeName);

    if (mutation.type === "childList" && mutation.target.id === "target") {
      // After receiving the notification that the child was removed,
      // further modifications to the detached subtree no longer trigger the observer.
      child.setAttribute("data-bar", "");
    }
  });
});

observer.observe(target, {
  attributes: true,
  childList: true,
  subtree: true,
});

target.removeChild(child);
// This change happens before the "childList target" notification is delivered,
// so it will also trigger the observer.
child.setAttribute("data-foo", "");

// Output:
// childList target null
// attributes child data-foo
// There is no "attributes child data-bar" notification.

В этом примере наблюдатель мутаций настроен для отслеживания изменений в атрибутах status и username во всех элементах, содержащихся в поддереве, отображающем имена пользователей в чате. Это позволяет коду, например, отражать изменения псевдонимов пользователей или отмечать их как отсутствующих (AFK) или оффлайн.

function callback(mutationList) {
  mutationList.forEach((mutation) => {
    switch (mutation.type) {
      case "attributes":
        switch (mutation.attributeName) {
          case "status":
            userStatusChanged(mutation.target.username, mutation.target.status);
            break;
          case "username":
            usernameChanged(mutation.oldValue, mutation.target.username);
            break;
        }
        break;
    }
  });
}

const userListElement = document.querySelector("#user-list");

const observer = new MutationObserver(callback);
observer.observe(userListElement, {
  attributeFilter: ["status", "username"],
  attributeOldValue: true,
  subtree: true,
});

В этом примере мы наблюдаем за элементом на предмет изменений значений атрибутов и добавляем кнопку, которая переключает атрибут dir элемента между "ltr" и "rtl". Внутри коллбека наблюдателя мы выводим старое значение атрибута.

HTML

<button id="toggle">Toggle direction</button><br />
<div id="container">
  <input type="text" id="rhubarb" dir="ltr" value="Tofu" />
</div>
<pre id="output"></pre>

CSS

body {
  background-color: paleturquoise;
}

button,
input,
pre {
  margin: 0.5rem;
}

JavaScript

const toggle = document.querySelector("#toggle");
const rhubarb = document.querySelector("#rhubarb");
const observerTarget = document.querySelector("#container");
const output = document.querySelector("#output");

toggle.addEventListener("click", () => {
  rhubarb.dir = rhubarb.dir === "ltr" ? "rtl" : "ltr";
});

const config = {
  subtree: true,
  attributeOldValue: true,
};

const callback = (mutationList) => {
  for (const mutation of mutationList) {
    if (mutation.type === "attributes") {
      output.textContent = `The ${mutation.attributeName} attribute was modified from "${mutation.oldValue}".`;
    }
  }
};

const observer = new MutationObserver(callback);
observer.observe(observerTarget, config);

Результат