Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

MutationObserver — observar alterações no DOM

MutationObserver regista alterações selecionadas do DOM e entrega os registos de forma assíncrona a uma função de retorno. Aprende como observe() configura a observação, takeRecords() esvazia a fila e disconnect() termina a observação.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

const observer = new MutationObserver((records, observer) => { /* handle records */ });
observer.observe(target, options);
const pending = observer.takeRecords();
observer.disconnect();

MutationObserver é uma API do padrão DOM, não faz parte do próprio ECMAScript. A função de retorno recebe um array de objetos MutationRecord e o observador. A notificação é colocada na fila como uma microtarefa, não sendo entregue de forma síncrona durante uma alteração; uma chamada pode conter vários registos. A presença do Node 24 num repositório não comprova a disponibilidade desta API de navegador.

MutationObserver.observe, chamado como observer.observe(target, options), seleciona um nó e os tipos de mutação: childList acompanha a adição e remoção de nós filhos (incluindo elementos, nós de texto e nós de comentário), attributes acompanha atributos e characterData acompanha dados de nós de texto e semelhantes. subtree: true inclui os descendentes. Depois de aplicados os valores predefinidos, tem de estar ativo pelo menos um tipo; caso contrário, é lançado um TypeError. attributeFilter restringe os nomes dos atributos; attributeOldValue e characterDataOldValue pedem os valores anteriores. As opções relativas a atributos ou dados podem ativar implicitamente o tipo de observação correspondente, mas definições explicitamente incompatíveis provocam um TypeError.

MutationObserver.takeRecords, chamado como observer.takeRecords(), devolve sincronamente os registos pendentes e esvazia a fila sem invocar a função de retorno nem terminar a observação. MutationObserver.disconnect, chamado como observer.disconnect(), termina todas as observações deste objeto e descarta os registos pendentes. Recupera-os primeiro se precisares deles. O objeto pode ser reiniciado com observe().

O exemplo observa um elemento desligado, recupera o registo antes da entrega da notificação e termina a observação. oldValue é null porque o atributo não existia anteriormente. Mantém a observação limitada; alterações feitas pela função de retorno podem gerar novas notificações.

Exemplos

{
  const target = document.createElement('div');
  const observer = new MutationObserver((records) => {
    console.log('callback:', records.length);
  });

  observer.observe(target, {
    attributes: true,
    attributeFilter: ['data-state'],
    attributeOldValue: true
  });

  target.setAttribute('data-state', 'ready');
  const records = observer.takeRecords();
  console.log(JSON.stringify(records.map((record) => ({
    type: record.type,
    attributeName: record.attributeName,
    oldValue: record.oldValue
  }))));

  observer.disconnect();
  target.setAttribute('data-state', 'done');
  console.log(observer.takeRecords().length);
}

Resultado

[{"type":"attributes","attributeName":"data-state","oldValue":null}]
0

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes