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

CKTIS / JavaScript

Opções de MutationObserver: tipos de mutação, subárvore, filtro e valores anteriores

Configura `observe()` para acompanhar alterações nos nós filhos, nos atributos ou nos dados de caracteres. Escolhe o âmbito da observação e quando guardar o valor anterior.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

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) cria um observador; observer.observe(target, options) inicia a observação de um nó do DOM. A função de retorno recebe um array de objetos MutationRecord e o observador. Esta API do DOM pertence à plataforma Web, não ao ECMAScript 2024; a disponibilidade depende do ambiente de execução.

childList assinala a adição ou remoção de filhos diretos de um nó observado (addedNodes, removedNodes). attributes assinala a adição, alteração ou remoção de atributos de um elemento. characterData assinala alterações num nó CharacterData existente, por exemplo ao alterar text.data. Atribuir um valor a textContent de um elemento substitui os seus filhos: se a lista de filhos mudar, a alteração é comunicada como childList, não como characterData. subtree: true estende os tipos de mutação escolhidos aos descendentes; por predefinição, só se observa target.

attributeFilter lista nomes locais de atributos, não seletores CSS. Com um filtro, só correspondem os atributos indicados que não têm espaço de nomes; sem filtro, são considerados todos os atributos. attributeOldValue: true e characterDataOldValue: true guardam o valor anterior à mutação correspondente na propriedade só de leitura record.oldValue. Não há uma opção oldValue nem um campo newValue. oldValue é null para childList, quando não se pediu a recolha do valor anterior ou quando o atributo ainda não existia.

childList é false por predefinição. Se attributes for omitido, passa a true quando se indica attributeFilter ou attributeOldValue; se characterData for omitido, passa a true quando se indica characterDataOldValue. Basta indicar a opção de valor anterior, mesmo com false. Caso contrário, ambos os tipos estão desativados por predefinição. observe() lança TypeError se nenhum tipo estiver ativo, se attributes: false for combinado com um filtro ou attributeOldValue: true, ou se characterData: false for combinado com characterDataOldValue: true.

Os registos chegam em lotes à função de retorno numa microtarefa, não durante a alteração do DOM. Com subtree: true, as inscrições temporárias permitem continuar a observar a subárvore de um descendente removido. A microtarefa de notificação elimina essas inscrições ao processar o observador, antes de qualquer chamada à função de retorno para esse lote. A eliminação das inscrições não depende da entrega de um registo de remoção: childList pode estar desativado ou takeRecords() pode já ter esvaziado a fila. disconnect() termina a observação e descarta os registos pendentes; se precisares deles, chama primeiro takeRecords(), que os devolve e esvazia a fila.

Exemplos

<!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 o exemplo completo num ficheiro `.html` e abre-o num navegador. Abre a consola de desenvolvimento e recarrega a página. Os nós não são inseridos na página. O filtro exclui `title` e as opções de valor anterior ativam `attributes` e `characterData`, que foram omitidas. A função de retorno escreve três registos pela ordem das mutações e termina a observação.

Lições relacionadas

  • JavaScript · Lição 31 · Intermédio · Versão: 3

Fontes