Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

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