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

CKTIS / JavaScript

MutationRecord — um registo de alterações do DOM

MutationRecord descreve uma única alteração observada no DOM. Saiba como identificar o tipo e o nó afetado, consultar os nós adicionados e removidos e obter o nome de um atributo e o respetivo valor anterior.

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

record.type; record.target; record.addedNodes; record.removedNodes; record.attributeName; record.oldValue

MutationRecord é uma interface apenas de leitura que descreve uma alteração do DOM observada por um MutationObserver. Os registos são passados no array fornecido à função de callback do observador; também é possível obter os registos pendentes com takeRecords(). Esta é uma API do DOM, não faz parte do ECMAScript. A MDN classifica-a como amplamente disponível nos browsers desde julho de 2015; a presença do Node 24 num projeto não comprova o suporte desta API de browser.

MutationRecord.type tem o valor "attributes", "characterData" ou "childList". MutationRecord.target identifica, respetivamente, o elemento cujo atributo foi alterado, o nó CharacterData alterado ou o nó cuja lista de filhos foi alterada — não o filho adicionado ou removido.

MutationRecord.addedNodes e MutationRecord.removedNodes são objetos NodeList que contêm os nós adicionados e removidos por essa alteração. Cada lista fica vazia quando não existem nós correspondentes. MutationRecord.attributeName contém o nome do atributo alterado para "attributes" e tem o valor null para os outros tipos.

MutationRecord.oldValue contém o valor anterior do atributo apenas quando attributeOldValue está ativado, ou os dados CharacterData anteriores apenas quando characterDataOldValue está ativado. Também é necessário observar o tipo de alteração correspondente. Nos restantes casos, incluindo "childList", o valor é null; um atributo que não existia anteriormente também pode ter um valor anterior null.

O exemplo observa um elemento desligado e lê os registos de forma síncrona com takeRecords(), que esvazia a fila. Assim, não é necessário esperar pelo callback. Depois de obter os registos, desliga o observador.

Exemplos

(() => {
  const root = document.createElement("div");
  root.setAttribute("data-state", "idle");
  const observer = new MutationObserver(() => {});
  observer.observe(root, {
    attributes: true,
    attributeOldValue: true,
    childList: true
  });

  root.setAttribute("data-state", "ready");
  const child = document.createElement("span");
  root.appendChild(child);
  root.removeChild(child);

  const records = observer.takeRecords();
  observer.disconnect();
  for (const record of records) {
    console.log(JSON.stringify([
      record.type,
      record.target === root,
      record.addedNodes.length,
      record.removedNodes.length,
      record.attributeName,
      record.oldValue
    ]));
  }
})();

Resultado

["attributes",true,0,0,"data-state","idle"]
["childList",true,1,0,null,null]
["childList",true,0,1,null,null]

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