Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

Opciones de MutationObserver: tipos de cambio, subárbol, filtro y valores anteriores

Configura `observe()` para seguir cambios en los nodos hijos, los atributos o los datos de caracteres. Elige el alcance de la observación y cuándo se debe guardar el valor anterior.

Versión: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxis

const observer = new MutationObserver((records, observer) => {
  for (const record of records) {
    // Read record.type, record.target, or record.oldValue.
  }
});

observer.observe(target, {
  childList: true,
  attributes: true,
  characterData: true,
  subtree: true,
  attributeFilter: ["data-state"],
  attributeOldValue: true,
  characterDataOldValue: true,
});

new MutationObserver(callback) crea un observador; observer.observe(target, options) inicia la observación de un nodo del DOM. La función de retorno recibe un array de objetos MutationRecord y el observador. Esta API del DOM pertenece a la plataforma web, no a ECMAScript 2024; su disponibilidad depende del entorno de ejecución.

childList notifica la adición o eliminación de hijos directos de un nodo observado (addedNodes, removedNodes). attributes notifica la adición, modificación o eliminación de atributos de un elemento. characterData notifica cambios en un nodo CharacterData existente, por ejemplo al modificar text.data. Asignar un valor a textContent de un elemento sustituye sus hijos: si cambia la lista de hijos, se notifica como childList, no como characterData. subtree: true extiende los tipos elegidos a los descendientes; por defecto solo se observa target.

attributeFilter enumera nombres locales de atributos, no selectores CSS. Con un filtro solo coinciden los atributos enumerados que no tienen espacio de nombres; sin filtro se tienen en cuenta todos los atributos. attributeOldValue: true y characterDataOldValue: true guardan el valor anterior a la mutación correspondiente en la propiedad de solo lectura record.oldValue. No existe una opción oldValue ni un campo newValue. oldValue es null para childList, cuando no se solicitó guardar el valor anterior o cuando el atributo no existía.

childList es false por defecto. Si se omite attributes, pasa a true cuando se indica attributeFilter o attributeOldValue; si se omite characterData, pasa a true cuando se indica characterDataOldValue. Basta con indicar la opción de valor anterior, incluso con false. En los demás casos ambos tipos están desactivados por defecto. observe() lanza TypeError si no se activa ningún tipo, si se combina attributes: false con un filtro o con attributeOldValue: true, o si se combina characterData: false con characterDataOldValue: true.

Los registros llegan por lotes a la función de retorno en una microtarea, no durante el cambio en el DOM. Con subtree: true, las suscripciones temporales permiten seguir observando el subárbol de un descendiente retirado. La microtarea de notificación elimina esas suscripciones al procesar el observador, antes de llamar a la función de retorno, si corresponde. No es necesario entregar un registro de retirada para eliminar las suscripciones: childList puede estar desactivado o takeRecords() puede haber vaciado ya la cola. disconnect() detiene la observación y descarta los registros pendientes; si los necesitas, llama antes a takeRecords() para recuperarlos y vaciar la cola.

Ejemplos

<!doctype html>
<meta charset="utf-8">
<title>MutationObserver options</title>
<script>
  const root = document.createElement("div");
  const item = document.createElement("span");
  const text = document.createTextNode("before");
  item.setAttribute("data-state", "idle");
  item.append(text);
  root.append(item);

  const observer = new MutationObserver((records, self) => {
    for (const record of records) {
      console.log(JSON.stringify([record.type, record.attributeName, record.oldValue]));
    }
    self.disconnect();
  });

  observer.observe(root, {
    childList: true,
    subtree: true,
    attributeFilter: ["data-state"],
    attributeOldValue: true,
    characterDataOldValue: true,
  });

  item.setAttribute("data-state", "ready");
  item.setAttribute("title", "ignored");
  text.data = "after";
  item.append(document.createElement("em"));
</script>

Resultado

["attributes","data-state","idle"]
["characterData",null,"before"]
["childList",null,null]

Guarda el ejemplo completo en un archivo `.html` y ábrelo en un navegador. Abre la consola de desarrollo y recarga la página. Los nodos no se insertan en la página. El filtro excluye `title` y las opciones de valor anterior activan `attributes` y `characterData`, que se han omitido. La función de retorno muestra tres registros en el orden de las mutaciones y después detiene la observación.

Lecciones relacionadas

  • JavaScript · Lección 31 · Intermedio · Versión: 3

Fuentes