MutationObserver 实战:监听 DOM 变化、批量异步处理与规避循环触发陷阱
什么时候需要监听 DOM 变化
多数时候我们不需要关心 DOM 什么时候变——自己的代码改完,自然知道结果。但有一类场景绕不开:变化不是自己触发的。比如等第三方 SDK 把组件注入页面后再初始化、追踪用户在富文本编辑器里的内容改动做自动保存、监听动态列表高度变化重算滚动区域。以前有人用 DOMNodeInserted 这类 Mutation Events,但它们是同步触发且严重拖慢渲染,早已被废弃。浏览器给出的现代答案是 MutationObserver——一个异步、批量、只在你指定的范围内工作的 DOM 变化观察器。
本文按「基础用法 → MutationRecord 字段 → 批处理时机 → 典型场景 → 循环陷阱 → 方案对比 → 封装」的顺序,把 MutationObserver 在工程里的实际用法讲清楚,代码可直接参考。
一、三行代码跑通
用法极简:new 一个观察器传入回调,用 observe 指定目标和观察项,不用时 disconnect。第二个参数的配置对象是关键——childList(子节点增删)、attributes(属性变化)、characterData(文本变化)三类至少要开一个,subtree 决定是否连后代一起看。
// 1. 建观察者:回调会在 DOM 变化后、微任务阶段批量触发
const observer = new MutationObserver((mutations, obs) => {
for (const m of mutations) {
console.log('变化类型:', m.type, '目标:', m.target);
}
});
// 2. 开始观察:第二个参数是配置,至少要开一类
observer.observe(document.body, {
childList: true, // 子节点的增删
subtree: true, // 连后代节点一起观察
attributes: true, // 属性变化
characterData: true // 文本节点内容变化
});
// 3. 暂停观察(不清空已入队的记录)
observer.disconnect();
最容易踩的坑是只开 childList 却发现后代节点变化没触发——childList: true 只看直接子节点,要看整个子树必须加 subtree: true。另一个坑是 attributes 只在显式设置属性时触发,用 element.style.color = 'red' 会触发(style 属性变了),但改 CSS 类导致的计算样式变化不会触发(DOM 属性本身没变)。
二、看懂 MutationRecord:变化的完整快照
回调收到的是 MutationRecord 数组,每条形如「哪个目标、什么类型、增删了哪些节点、属性旧值是什么」的完整快照。不同类型关注不同字段。
// MutationRecord 的字段速查
observer = new MutationObserver((mutations) => {
mutations.forEach((m) => {
switch (m.type) {
case 'childList':
// m.addedNodes / m.removedNodes 是 NodeList
m.addedNodes.forEach(n => console.log('新增:', n.nodeName));
break;
case 'attributes':
// m.attributeName 告诉我们哪个属性变了,m.oldValue 需开启 attributeOldValue
console.log('属性', m.attributeName, '从', m.oldValue, '变为', m.target.getAttribute(m.attributeName));
break;
case 'characterData':
// m.oldValue 需开启 characterDataOldValue
console.log('文本变化:', m.oldValue, '->', m.target.data);
break;
}
});
});
observer.observe(el, {
childList: true, subtree: true, attributes: true,
attributeOldValue: true, characterData: true, characterDataOldValue: true
});
注意 oldValue 不是默认给的:要拿到属性旧值必须开 attributeOldValue: true,要拿文本旧值必须开 characterDataOldValue: true。少了这两个配置,m.oldValue 永远是 null——很多人调试半天才发现是配置漏了。
addedNodes 和 removedNodes 是 NodeList 不是数组,要用 forEach 或 Array.from 遍历。另外删除节点时,被删的节点对象仍在 removedNodes 里,可以读它的内容做清理,但它的父节点已经是 null 了。
三、批处理时机:为什么连续三次修改只回调一次
这是 MutationObserver 最重要也最容易被误解的特性:回调是异步的,且在微任务阶段批量投递。同步代码里连续改三次 DOM,不会触发三次回调,而是把这三条记录攒成一批,等同步代码执行完再一次性交给回调。
// 批量异步:三次连续修改只会触发一次回调
const box = document.querySelector('#list');
const obs = new MutationObserver((mutations) => {
// mutations 里包含了这一批的所有 3 次变化
console.log('本批共收到', mutations.length, '条变化');
});
obs.observe(box, { childList: true });
box.appendChild(makeItem('A'));
box.appendChild(makeItem('B'));
box.appendChild(makeItem('C'));
// 同步代码结束后,微任务阶段回调只执行一次,mutations.length === 3
// takeRecords:在 disconnect 前取走尚未投递的记录
const pending = obs.takeRecords();
obs.disconnect();
这个设计带来两个直接好处:一是性能——UI 不需要为每次 DOM 操作都跑一遍监听逻辑;二是一致性——回调执行时,DOM 已经是你这批操作完成后的最终状态,不会看到中间态。想主动取走还没投递的记录,用 takeRecords(),它会清空队列并返回记录数组,常和 disconnect() 配合做「收尾前把欠账处理掉」。
要特别区分 disconnect 和 takeRecords:disconnect 只是停止观察、不会丢弃已入队但未投递的记录(如果观察器之后不再有引用,这些记录会被 GC);takeRecords 则是把待投递的记录取出来交给你的代码处理。
四、场景一:等第三方脚本注入的组件就绪
接入第三方组件时经常要「等它出现再初始化」。轮询 setInterval 既浪费又有时延,用 MutationObserver 可以在目标节点出现的瞬间得到通知,第一时间接管。
// 场景:等第三方 SDK 把广告位注入到容器后,再初始化业务
function waitForElement(selector, { timeout = 5000 } = {}) {
return new Promise((resolve, reject) => {
const existing = document.querySelector(selector);
if (existing) return resolve(existing);
const obs = new MutationObserver(() => {
const el = document.querySelector(selector);
if (el) {
obs.disconnect(); // 找到了立刻停止,避免继续消耗
clearTimeout(timer);
resolve(el);
}
});
obs.observe(document.documentElement, { childList: true, subtree: true });
const timer = setTimeout(() => {
obs.disconnect();
reject(new Error('等待元素超时: ' + selector));
}, timeout);
});
}
waitForElement('#third-party-widget').then(el => initBusiness(el));
这个封装做了三件正确的事:先查一次是否已存在(避免观察后才出现的竞态)、找到后立刻 disconnect(不再继续消耗)、加了超时兜底(第三方脚本失败时不至于永久挂起)。这是 MutationObserver 最经典也最实用的用法,值得直接收进工具库。
五、场景二:动态内容的高度与布局重算
聊天窗口、日志面板这类容器,内容会不断追加,需要实时重算滚动高度。用 MutationObserver 监听内容区,配合 requestAnimationFrame 节流,可以把一帧内的多次变化合并成一次布局计算。
// 场景:内容区高度随动态内容变化,重算滚动容器
const content = document.querySelector('#content');
const obs = new MutationObserver(() => {
// 用 requestAnimationFrame throttle,避免一帧内多次重排
if (rafId) return;
rafId = requestAnimationFrame(() => {
rafId = 0;
syncHeight(content.scrollHeight);
});
});
let rafId = 0;
obs.observe(content, { childList: true, subtree: true, characterData: true });
function syncHeight(h) {
document.querySelector('#scroller').style.maxHeight = h + 'px';
}
这里加 rafId 节流的原因是:MutationObserver 回调可能在微任务里连续触发多次,如果每次都读 scrollHeight 并写样式,会造成强制同步布局(layout thrashing)。把写入放进下一帧的 rAF,浏览器能把读写分开,性能更稳。这个「观察 + rAF 节流」的组合是处理 DOM 驱动布局的标准套路。
六、场景三:编辑器变更追踪与自动保存
富文本编辑器的内容变化时自动保存,是 MutationObserver 的另一类高频应用。关键难点是区分用户输入和程序写入——如果用 setContent 之类的 API 程序化改内容,也会触发观察器,不加判断就会把这个「自己人」的变化当成用户编辑,导致无意义的自动保存。
// 场景:追踪富文本编辑器的变更,做「脏标记」与自动保存
let dirty = false;
const obs = new MutationObserver((mutations) => {
// 过滤掉程序自己 setContent 造成的变更
if (programmaticChange) return;
dirty = true;
scheduleAutoSave();
});
obs.observe(editor, { childList: true, subtree: true, characterData: true, attributes: true });
let saveTimer;
function scheduleAutoSave() {
clearTimeout(saveTimer);
saveTimer = setTimeout(() => { autoSave(editor.innerHTML); dirty = false; }, 3000);
}
代码用 programmaticChange 标记位跳过程序写入,用 debounce(3 秒无变化才保存)合并连续输入。真实项目里还应监听 beforeunload,在页面关闭前把未保存的内容 flush 掉,避免用户最后几秒的输入丢失。
七、循环触发陷阱:MutationObserver loop limit exceeded
这是 MutationObserver 最危险也最隐蔽的问题:如果在回调里修改被观察的 DOM,会再次触发回调。如果每次回调都改一次,就会无限循环,浏览器最终抛出 MutationObserver loop completed with undelivered notifications 或 loop limit exceeded 错误并丢弃剩余通知。
// 陷阱:回调里改 DOM,又被自己观察到 -> 「MutationObserver loop limit exceeded」
const obs = new MutationObserver((mutations, observer) => {
mutations.forEach(m => {
if (m.type === 'attributes' && m.attributeName === 'data-done') {
// 错误写法:这里再改被观察的属性,会再次触发回调
// m.target.setAttribute('data-done', '1'); // 💥 循环
}
});
});
// 正确做法一:改之前先 disconnect,改完再 observe
const obs2 = new MutationObserver((mutations, observer) => {
observer.disconnect(); // 先断开
mutations.forEach(m => doSideEffect(m));
observer.observe(target, config); // 处理完再连回
});
// 正确做法二:用标记位跳过「自己造成的」变化
let selfEditing = false;
const obs3 = new MutationObserver(() => {
if (selfEditing) return;
selfEditing = true;
doChange();
selfEditing = false; // 同一微任务内产生的记录会被忽略
});
代码给了两种正确写法。第一种是先 disconnect、处理完再 observe,让副作用期间的变化不被记录;第二种是标记位跳过,在 selfEditing 为 true 时忽略回调。注意标记位复位要在同一微任务内完成,否则后续真正的变化会被误跳过。实际排查这类问题时,重点看回调里有没有 setAttribute、appendChild 之类针对观察目标的写操作。
八、和其它 Observer 的取舍
浏览器提供了三个职责不同的 Observer,选错工具会事倍功半:
- MutationObserver:观察 DOM 结构、属性、文本的变化,回答"节点增删了吗、属性改了吗"。
- ResizeObserver:观察元素内容盒尺寸变化,回答"元素变大变小了吗",做响应式布局最合适;注意
display: none时不会触发。 - IntersectionObserver:观察元素是否进入/离开视口,回答"用户看到它了吗",做懒加载、曝光埋点最合适。
// MutationObserver vs ResizeObserver vs IntersectionObserver
// 1) 观察 DOM 结构/属性变化 -> MutationObserver
new MutationObserver(cb).observe(el, { childList: true, subtree: true });
// 2) 观察元素尺寸变化(不含 display:none)-> ResizeObserver
new ResizeObserver(entries => {
const { width, height } = entries[0].contentRect;
}).observe(el);
// 3) 观察元素是否进入视口 -> IntersectionObserver
new IntersectionObserver(entries => {
if (entries[0].isIntersecting) lazyLoad();
}).observe(el);
// 4) 已废弃的 Mutation Events(性能差,会同步阻塞),不要用:
// el.addEventListener('DOMNodeInserted', cb); // ❌ deprecated
一句话总结:结构变化用 Mutation,尺寸变化用 Resize,可见性变化用 Intersection。三者可以组合使用,比如用 IntersectionObserver 触发懒加载、再用 MutationObserver 监听加载后的内容变化,各司其职。
九、一个可复用的封装
实际项目里建议包一层:支持谓词过滤(只处理关心的变化)、可选节流、并在实例销毁时统一清理,避免忘记 disconnect 导致内存泄漏。
// 一个极简的封装:自动清理 + 谓词过滤 + 节流
class DOMWatcher {
constructor(target, config, handler, { throttle = 0 } = {}) {
this.target = target;
this.observer = new MutationObserver((mutations) => {
const hits = mutations.filter(handler.filter || (() => true));
if (!hits.length) return;
if (throttle) {
clearTimeout(this.timer);
this.timer = setTimeout(() => handler(hits), throttle);
} else {
handler(hits);
}
});
this.observer.observe(target, config);
}
disconnect() {
clearTimeout(this.timer);
this.observer.disconnect();
}
}
const watcher = new DOMWatcher(list, { childList: true }, (ms) => {
console.log('有效变化', ms.length);
}, { throttle: 100 });
这个封装把「过滤 + 节流 + 清理」三件事收进类里,业务代码只关心「变化了要做什么」。真实场景还可以加:自动在组件卸载钩子(如 React 的 useEffect cleanup、Vue 的 onUnmounted)里调用 disconnect,以及用 takeRecords 在销毁前处理最后的未投递记录。
性能与注意事项
MutationObserver 是异步批量的,性能远好于废弃的 Mutation Events,但也不是零成本。几点建议:观察范围尽量收窄,能只观察某个容器就别观察 document.body;subtree: true 会显著扩大监听面,非必要不开;回调里避免同步读取大量布局属性;组件销毁时务必 disconnect。此外它只在主线程 DOM 变化时触发,Shadow DOM 内部的变化需要单独对 shadowRoot 观察。
小结
MutationObserver 用异步批量的方式解决了「监听 DOM 变化」这个曾经很痛的问题。掌握四个要点就能用好它——配置决定观察范围(childList/attributes/characterData + subtree)、回调在微任务阶段批量投递、oldValue 需要显式开启、回调里改观察目标会循环触发,要用 disconnect 或标记位规避。下次遇到「等第三方组件就绪」「追踪编辑器内容」「动态布局重算」这类需求,别再写轮询了,用观察器更优雅也更省心。
本文为原创实践记录,所有示例均为原生 JavaScript、零依赖,可直接在现代浏览器运行验证,欢迎交流更优雅的 DOM 变化监听方案。
- 点赞
- 收藏
- 关注作者
评论(0)