CKTIS / JavaScript
MutationObserver — observar cambios del DOM
MutationObserver registra cambios seleccionados del DOM y entrega los registros de forma asíncrona a una función de notificación. Aprende cómo observe() configura la observación, takeRecords() vacía la cola y disconnect() detiene la observación.
Versión: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxis
const observer = new MutationObserver((records, observer) => { /* handle records */ });
observer.observe(target, options);
const pending = observer.takeRecords();
observer.disconnect();MutationObserver es una API del estándar DOM, no forma parte de ECMAScript. La función de notificación (callback) recibe un array de objetos MutationRecord y el observador. La notificación se pone en cola como una microtarea y no se entrega de forma síncrona durante un cambio; una llamada puede incluir varios registros. Que Node 24 esté en un repositorio no demuestra que esta API de navegador esté disponible.
MutationObserver.observe, llamado como observer.observe(target, options), selecciona un nodo y los tipos de mutación: childList registra la adición y eliminación de hijos, attributes registra atributos y characterData registra datos de nodos de texto y similares. subtree: true incluye los descendientes. Tras aplicar los valores predeterminados, debe estar activado al menos un tipo; de lo contrario, se lanza un TypeError. attributeFilter limita los nombres de atributos; attributeOldValue y characterDataOldValue solicitan los valores anteriores. Las opciones relacionadas con atributos o datos pueden activar implícitamente su tipo de observación correspondiente, pero los ajustes explícitamente incompatibles provocan un TypeError.
MutationObserver.takeRecords, llamado como observer.takeRecords(), devuelve síncronamente los registros pendientes y vacía la cola, sin invocar la función de notificación ni detener la observación. MutationObserver.disconnect, llamado como observer.disconnect(), detiene todas las observaciones de este objeto y descarta los registros pendientes. Recupéralos antes si los necesitas. El objeto se puede reiniciar con observe().
El ejemplo observa un elemento que no está conectado al documento, recupera su registro antes de que se entregue la notificación y detiene la observación. oldValue es null porque el atributo no existía anteriormente. Limita el alcance de la observación; las mutaciones realizadas por la función de notificación pueden generar más notificaciones.
Ejemplos
{
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}]
0El código mostrado y el resultado declarado se verificaron en un entorno aislado mediante el método registrado en la evidencia de verificación de esta versión exacta.