CKTIS / JavaScript
MutationObserver: observe(), disconnect() y takeRecords()
Observa cambios concretos del DOM, recupera los registros pendientes sin esperar a la función de retorno de llamada y decide si conservarlos al detener la observación.
Versión: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxis
const observer = new MutationObserver(callback);
observer.observe(target, options);
const records = observer.takeRecords();
observer.disconnect();new MutationObserver(callback) crea un observador, pero no inicia la observación. observe(target, options), disconnect() y takeRecords() son métodos de instancia, no estáticos. Los cambios que coinciden con las opciones se encolan; una microtarea de notificación entrega un lote a callback(records, observer) en vez de llamar a la función de forma síncrona por cada cambio.
observe(target, options) registra un nodo del DOM (Node) y devuelve undefined. Otras llamadas pueden añadir objetivos o actualizar las opciones para el mismo objetivo. childList detecta adiciones y eliminaciones de hijos directos, attributes detecta cambios de atributos y characterData detecta cambios en los datos de un nodo, como el contenido de un nodo de texto. subtree: true aplica las mismas reglas a los descendientes. Los cambios en una rama eliminada aún pueden encolarse antes de la siguiente microtarea de notificación.
attributeFilter limita los nombres de atributos observados. attributeOldValue: true y characterDataOldValue: true guardan el valor anterior en oldValue. Si omites attributes, indicar attributeFilter o attributeOldValue activa la observación de atributos; characterDataOldValue activa de forma análoga characterData si se omite. observe() lanza TypeError si no hay ningún tipo de cambio activado, si combinas attributes: false con un filtro o con attributeOldValue: true, o si combinas characterData: false con characterDataOldValue: true.
takeRecords() devuelve de forma síncrona un array de objetos MutationRecord pendientes ([] si la cola está vacía) y vacía la cola. No detiene la observación ni llama a la función de retorno de llamada: tú procesas esos registros. disconnect() devuelve undefined, deja de observar todos los objetivos de la instancia y descarta los registros no entregados. Para conservarlos, llama a takeRecords() justo antes de disconnect(). Puedes reutilizar el observador con otra llamada a observe().
Es una API del DOM de la plataforma web y no forma parte de ECMAScript 2024. Su disponibilidad depende del entorno de ejecución. El observador no concede acceso a nodos que de otra forma serían inaccesibles, como los de un iframe de otro origen.
Ejemplos
<!doctype html>
<meta charset="utf-8">
<title>MutationObserver example</title>
<script>
const target = document.createElement('div');
const options = { attributes: true, attributeFilter: ['data-state'] };
const observer = new MutationObserver((records, currentObserver) => {
console.log(`callback: ${records.length} ${records[0].attributeName}`);
currentObserver.disconnect();
});
observer.observe(target, options);
target.setAttribute('data-state', 'first');
const [record] = observer.takeRecords();
console.log(`taken: ${record.type} ${record.attributeName}`);
target.setAttribute('data-state', 'discarded');
observer.disconnect();
target.setAttribute('data-state', 'unobserved');
console.log(`remaining: ${observer.takeRecords().length}`);
observer.observe(target, options);
target.setAttribute('data-state', 'delivered');
</script>Resultado
taken: attributes data-state remaining: 0 callback: 1 data-state
Guarda el ejemplo completo como archivo HTML, ábrelo en un navegador y consulta la consola de desarrollo. El elemento no se inserta en la página. `takeRecords()` recupera el primer registro, `disconnect()` descarta el segundo y el cambio durante la desconexión no se registra. Solo llega a la función de retorno de llamada el cambio posterior a la reanudación.
Lecciones relacionadas
- JavaScript · Lección 31 · Intermedio · Versión: 3