CKTIS / JavaScript
MutationObserver: observe(), disconnect() e takeRecords()
Observa alterações específicas no DOM, recolhe os registos pendentes sem esperar pela função de retorno e decide se os queres conservar ao parar a observação.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
const observer = new MutationObserver(callback);
observer.observe(target, options);
const records = observer.takeRecords();
observer.disconnect();new MutationObserver(callback) cria um observador, mas não inicia a observação. observe(target, options), disconnect() e takeRecords() são métodos de instância, não métodos estáticos. As alterações que correspondem às opções entram numa fila; uma microtarefa de notificação entrega um lote a callback(records, observer) em vez de chamar a função de forma síncrona a cada alteração.
observe(target, options) regista um nó do DOM (Node) e devolve undefined. Outras chamadas podem acrescentar alvos ou atualizar as opções do mesmo alvo. childList deteta a adição e a remoção de filhos diretos, attributes deteta alterações de atributos e characterData deteta alterações nos dados de um nó, como o conteúdo de um nó de texto. subtree: true aplica as mesmas regras aos descendentes. As alterações num ramo removido ainda podem entrar na fila antes da próxima microtarefa de notificação.
attributeFilter limita os nomes dos atributos observados. attributeOldValue: true e characterDataOldValue: true guardam o valor anterior em oldValue. Se attributes for omitido, indicar attributeFilter ou attributeOldValue ativa a observação de atributos; da mesma forma, indicar characterDataOldValue ativa characterData quando este é omitido. observe() lança TypeError se nenhum tipo de alteração estiver ativo, se attributes: false for combinado com um filtro ou com attributeOldValue: true, ou se characterData: false for combinado com characterDataOldValue: true.
takeRecords() devolve de forma síncrona um array de objetos MutationRecord pendentes ([] se a fila estiver vazia) e esvazia a fila. Não para a observação nem chama a função de retorno: cabe-te tratar os registos devolvidos. disconnect() devolve undefined, para a observação de todos os alvos dessa instância e descarta os registos ainda não entregues. Para os conservar, chama takeRecords() imediatamente antes de disconnect(). Podes voltar a usar o observador com outra chamada a observe().
Esta é uma API do DOM da plataforma Web, não faz parte do ECMAScript 2024. A disponibilidade depende do ambiente de execução. O observador não concede acesso a nós que seriam inacessíveis de outra forma, como os de um iframe de outra origem.
Exemplos
<!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 o exemplo completo num ficheiro HTML, abre-o num navegador e consulta a consola de programador. O elemento não é inserido na página. `takeRecords()` recolhe o primeiro registo, `disconnect()` descarta o segundo e a alteração durante a interrupção não é registada. Só a alteração após o reinício chega à função de retorno.
Lições relacionadas
- JavaScript · Lição 31 · Intermédio · Versão: 3