MutationObserver
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( |
---|
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 MutationRecord
s.
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 |
|
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 |
|
Retorna os nós adicionados. Será uma NodeList vazia se nenhum nó foi adicionado. |
removedNodes |
|
Retorna os nós removidos. Será uma NodeList vazia se nenhum nó foi removido. |
previousSibling |
|
Retorna o irmão anterior dos nós adicionados ou removidos, ou null . |
nextSibling |
|
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