CKTIS / JavaScript
MutationRecord: como ler uma alteração no DOM
Identifica o tipo de alteração e o nó afetado, examina os filhos adicionados ou removidos e verifica quando o registo contém o valor anterior.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
const { type, target, addedNodes, removedNodes, attributeName, oldValue } = record;Um MutationRecord descreve uma única alteração no DOM. Um MutationObserver entrega os registos à função de callback numa microtarefa, não durante a alteração em si. Estas propriedades são só de leitura. Começa por type para interpretar os restantes campos. Esta API pertence à plataforma web, não ao ECMAScript 2024; não assumas que está disponível num ambiente sem DOM.
Se type === "childList", target é o nó cujos filhos diretos mudaram. addedNodes e removedNodes são objetos NodeList com os filhos adicionados e removidos por essa alteração, respetivamente. Se não tiver sido adicionado ou removido nenhum filho, a lista correspondente está vazia, não é null. Mover um nó pode produzir registos separados de remoção e adição.
Se type === "attributes", target é o elemento alterado. attributeName contém o nome local do atributo, sem o prefixo do espaço de nomes. oldValue contém o valor anterior do atributo como cadeia de caracteres se observe() tiver sido configurado com attributeOldValue: true. Caso contrário, vale null, tal como quando o atributo não existia anteriormente.
Se type === "characterData", target é o próprio nó CharacterData, por exemplo um nó de texto, e não o seu nó pai. oldValue contém os dados anteriores como cadeia de caracteres apenas com characterDataOldValue: true; caso contrário, vale null. Para "childList", oldValue vale sempre null. Fora do caso "attributes", attributeName vale null, e fora do caso "childList", ambas as listas de nós estão vazias.
Com subtree: true, o target do registo pode ser um descendente do nó passado a observe(). Não existe um campo newValue: ler os dados de target devolve o estado atual, que pode já refletir alterações posteriores.
Exemplos
<!doctype html>
<meta charset="utf-8">
<title>MutationRecord example</title>
<script>
(() => {
const root = document.createElement("div");
const text = document.createTextNode("hello");
const child = document.createElement("span");
root.setAttribute("data-state", "before");
root.append(text);
const observer = new MutationObserver(() => {});
observer.observe(root, {
attributes: true,
attributeOldValue: true,
characterData: true,
characterDataOldValue: true,
childList: true,
subtree: true,
});
root.setAttribute("data-state", "after");
text.data = "world";
root.append(child);
child.remove();
const records = observer.takeRecords();
observer.disconnect();
const nodeNames = (nodes) => Array.from(nodes, (node) => node.nodeName);
for (const { type, target, addedNodes, removedNodes, attributeName, oldValue } of records) {
console.log(JSON.stringify([
type, target.nodeName, nodeNames(addedNodes), nodeNames(removedNodes),
attributeName, oldValue,
]));
}
})();
</script>Resultado
["attributes","DIV",[],[],"data-state","before"] ["characterData","#text",[],[],null,"hello"] ["childList","DIV",["SPAN"],[],null,null] ["childList","DIV",[],["SPAN"],null,null]
Guarda o exemplo completo como ficheiro HTML, abre-o num navegador e verifica o resultado na consola. `takeRecords()` recolhe os registos e esvazia a fila antes da chamada à função de callback, pelo que o código apresenta quatro registos por ordem. O registo de adição continua a incluir `SPAN`, mesmo tendo o nó sido removido depois.
Lições relacionadas
- JavaScript · Lição 31 · Intermédio · Versão: 3
Fontes
- MutationRecord
- MutationRecord: target property
- MutationRecord: addedNodes property
- MutationRecord: removedNodes property
- MutationRecord: attributeName property
- MutationRecord: oldValue property
- MutationObserver: observe() method
- MutationObserver: takeRecords() method
- Using microtasks in JavaScript with queueMicrotask()