CKTIS / JavaScript
MutationRecord: cómo leer un cambio en el DOM
Identifica el tipo de cambio y el nodo afectado, examina los hijos añadidos o eliminados y comprueba cuándo el registro contiene el valor anterior.
Versión: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxis
const { type, target, addedNodes, removedNodes, attributeName, oldValue } = record;Un MutationRecord describe un cambio en el DOM. En lugar de entregar los registros durante el cambio, MutationObserver los pasa en una microtarea a la función que se le proporcionó al crearlo. Estas propiedades son de solo lectura. Empieza por type para interpretar los demás campos. Esta API pertenece a la plataforma web, no a ECMAScript 2024; no des por hecho que está disponible en un entorno sin DOM.
Si type === "childList", target es el nodo cuyos hijos directos cambiaron. addedNodes y removedNodes son objetos NodeList que contienen, respectivamente, los hijos añadidos y eliminados por ese cambio. Si no se añadió o eliminó ninguno, la lista correspondiente está vacía, no es null. Mover un nodo puede producir registros separados de eliminación y adición.
Si type === "attributes", target es el elemento modificado. attributeName contiene el nombre local del atributo, sin prefijo de espacio de nombres. oldValue contiene el valor anterior del atributo como cadena si se activó attributeOldValue: true en observe(). Si no se activó, vale null, al igual que cuando el atributo no existía antes.
Si type === "characterData", target es el propio nodo CharacterData, por ejemplo un nodo de texto, no su padre. oldValue contiene los datos anteriores como cadena solo con characterDataOldValue: true; si no, vale null. Para "childList", oldValue siempre vale null. Fuera del caso "attributes", attributeName vale null, y fuera del caso "childList", ambas listas de nodos están vacías.
Con subtree: true, el target del registro puede ser un descendiente del nodo que se pasó a observe(). No hay un campo newValue: leer los datos de target devuelve el estado actual, que puede reflejar ya cambios posteriores.
Ejemplos
<!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 el ejemplo completo como archivo HTML, ábrelo en un navegador y comprueba la salida en la consola. `takeRecords()` recoge los registros y vacía la cola antes de que el observador llame a la función que se le pasó, por lo que el código muestra cuatro registros en orden. El registro de adición sigue incluyendo `SPAN` aunque el nodo se haya eliminado después.
Lecciones relacionadas
- JavaScript · Lección 31 · Intermedio · Versión: 3
Fuentes
- 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()