MutationObserver

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

MutationObserver fornece aos desenvolvedores uma maneira de reagir a mudanças em um DOM. Ele é concebido como um substituto para Mutation Events definido na especificação de eventos DOM nível 3.

Constructor

`MutationObserver()`

Construtor para instanciar novos observadores de mutação do DOM.

MutationObserver(
  function callback
);

Parâmetros

callback: A função que será chamada em cada mutação do DOM. O observador irá chamar esta função com dois argumentos. O primeiro é um array de objetos, cada um do tipo MutationRecord. O segundo é a essa instância MutationObserver.

Métodos da instância

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

`observe()`

Registra a instância MutationObserver para receber notificações das mutações do DOM no nó especificado.

void observe(
  Node target,
  MutationObserverInit options
);

Parâmetros

target: O Node no qual é observadas as mutações do DOM.
options: Um objeto MutationObserverInit especifica quais mutações DOM devem ser reportadas.

Nota: NOTA: Adicionar um observador para um elemento é como utilizar o addEventListener, se você observar o elemento várias vezes não faz diferença. Ou seja, se você observar um elemento duas vezes, o callback do observador não disparará duas vezes, nem você deverá executar duas vezes o disconnect(). Em outras palavras, uma vez que um elemento é observado, observá-lo novamento com a mesma instância do observador não fará nada. No entanto, se o objeto callback for diferente, ele, é claro, adicionará outro observador para isso.

`disconnect()`

Pára o rebimento de notificações das mutações do DOM na instância MutationObserver. O callback do observador não será invocado até que método observe() seja novamente utilizado.

void disconnect();

`takeRecords()`

Esvazia a fila de registro da instância MutationObserver e retorna o que estava nela.

Array takeRecords();

Valor de retorno

Retorna um Array de MutationRecords.

`MutationObserverInit`

MutationObserverInit é um objeto que pode especificar as seguintes propriedades:

Nota: NOTA: No mínimo childList, attributes, ou characterData devem ser definidos como true. Caso contrário o erro "An invalid or illegal string was specified" é lançado.

Property	Description
`childList`	Defina como `true` se adições e remoções dos elementos filho do nó alvo (incluindo nós de texto) devem ser observadas.
`attributes`	Defina como `true` se mutações dos atributos do alvo devem ser observadas.
`characterData`	Defina como `true` se mutações dos dados do alvo devem ser observadas.
`subtree`	Defina como `true` se mutações não apenas do alvo, mas também dos descendentes do alvo devem ser observadas.
`attributeOldValue`	Defina como `true` se `attributes` é definido como `true` e o valor do atributo do alvo antes da mutação precisa ser gravado.
`characterDataOldValue`	Defina como `true` se `characterData` é definido como `true` e os dados do alvo antes da mutação precisam ser gravados.
`attributeFilter`	Defina como um array de nomes locais de atributo (sem namespace) se nem todas mutações de atributo precisam ser observadas.

`MutationRecord`

MutationRecord é um objeto que será passado para o callback do observador. Tem as seguintes propriedades:

Property	Type	Description
`type`	`String`	Retorna `attributes` se a mutação foi a de um atributo, `characterData` se foi de um nó `CharacterData`, e `childList` se foi a mutação para uma árvore de nós.
`target`	`Node`	Retorna o nó que a mutação afetou, dependendo do `type`. Para `attributes`é o elemento cujo atributo mudou. Para `characterData` é o nó `CharacterData`. Para `childList` é o nó cujos filhos mudaram.
`addedNodes`	`NodeList`	Retorna os nós adicionados. Será uma NodeList vazia se nenhum nó foi adicionado.
`removedNodes`	`NodeList`	Retorna os nós removidos. Será uma NodeList vazia se nenhum nó foi removido.
`previousSibling`	`Node`	Retorna o irmão anterior dos nós adicionados ou removidos, ou `null`.
`nextSibling`	`Node`	Retorna o próximo irmão dos nós adicionados ou removidos, ou `null`.
`attributeName`	`String`	Retorna o nome local do atributo modificado, ou `null`.
`attributeNamespace`	`String`	Retorna o namespace do atributo modificado, ou `null`.
`oldValue`	`String`	O valor retornado depende do `type`. Para `attributes`, é o valor do atributo modificado antes da troca. Para `characterData`, são os dados do nó modificado antes da troca. Para `childList` é `null`.

Exemplo de uso

O exemplo a seguir foi retirado deste post.

// seleciona o nó alvo
var target = document.querySelector("#some-id");

// cria uma nova instância de observador
var observer = new MutationObserver(function (mutations) {
  mutations.forEach(function (mutation) {
    console.log(mutation.type);
  });
});

// configuração do observador:
var config = { attributes: true, childList: true, characterData: true };

// passar o nó alvo, bem como as opções de observação
observer.observe(target, config);

// mais tarde você pode parar de observar
observer.disconnect();

Leitura adicional

A brief overview
A more in-depth discussion
A screencast by Chromium developer Rafael Weinstein
The mutation summary library
The DOM standard que define a interface do MutationObserver

Especificações

Specification
DOM Standard # interface-mutationobserver

Compatibilidade com navegadores

BCD tables only load in the browser