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
- MutationObserver: observe() method
- MutationObserver: MutationObserver() constructor
- MutationRecord
- MutationRecord: oldValue property
- Node: textContent property
- Using microtasks in JavaScript with queueMicrotask()
- HTML Standard — Event loops
- MutationObserver: disconnect() method
- MutationObserver: takeRecords() method