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( |
---|
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