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.oldValueMutationRecord é 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.