- 前端
- 教程
【免费下载链接】30-seconds-of-react
Short React code snippets for all your development needs
导读
本文围绕 30-seconds-of-react 仓库中的useMutationObserver代码片段展开，讲解如何把浏览器原生MutationObserverAPI 封装成 React Hook，在组件生命周期内监听指定 DOM 节点的属性、文本与子节点变化，并在卸载时自动清理监听器。读完本文，你将掌握该 Hook 的逐行实现原理、MutationObserverInit全部配置项的含义、一个可运行的计数演示 Demo，以及在实际项目中正确使用与避坑的关键细节。
一、先看原始片段：它解决什么问题
这个片段位于仓库 snippets/use-mutation-observer.md，frontmatter 中标明其类型为snippet、标签为hooks,effect，最后更新于 2021-11-23。它的定位一句话可以概括：
使用
MutationObserver监听 DOM 树发生的变化（属性、文本、子节点增删等），并把监听的生命周期托管给 React 的useEffect()。
在很多场景下，你并不需要主动轮询 DOM，而是希望在某个元素被脚本或用户修改时得到通知——例如文本被编辑、样式属性被改写、子节点被增删。原生MutationObserver正是为此设计的浏览器 API，而这个 Hook 的价值在于：
- 用
useEffect()把观察器的创建、绑定、销毁与 React 渲染生命周期对齐； - 依赖
callback与options，让监听行为随参数变化自动重建； - 组件卸载时自动调用
disconnect()，避免内存泄漏。
二、核心实现逐行拆解
原始实现非常紧凑，完整代码如下（见 snippets/use-mutation-observer.md#L18-L35）：
const useMutationObserver = ( ref, callback, options = { attributes: true, characterData: true, childList: true, subtree: true, } ) => { React.useEffect(() => { if (ref.current) { const observer = new MutationObserver(callback); observer.observe(ref.current, options); return () => observer.disconnect(); } }, [callback, options]); };对照原文档给出的四步工作流，可以逐一对应：
- 使用
useEffect()且依赖callback与options：只要回调函数或配置对象发生变化，Effect 就会重新执行，相当于"重建观察器"； - 检查
ref是否已初始化：if (ref.current)确保目标节点已经挂载到真实 DOM（比如由父组件通过ref传入的节点在首次渲染时可能尚未就绪）； - 创建
MutationObserver并调用observe()：new MutationObserver(callback)注册回调，observer.observe(ref.current, options)开始按options配置监听目标节点； - 卸载时
disconnect()：Effect 的清理函数返回() => observer.disconnect()，组件卸载（或依赖项变化触发重跑）时断开观察器，停止所有后续通知并释放引用。
值得注意的是，该仓库的贡献规范（见 CONTRIBUTING.md）要求使用const MyComponent = ...形式定义函数、使用单引号字符串、采用 2 空格软缩进，这个片段完全符合仓库约定；同时它只使用React.useEffect等React.前缀调用方式，没有引入额外的第三方依赖。
三、原生 MutationObserver API 速览：Hook 背后的浏览器能力
要真正理解这个 Hook，需要先弄清楚它封装的底层 API。MutationObserver是浏览器内置的 Web API（并非 React 专有），核心有三个方法：
| 方法 | 作用 | 在本 Hook 中的使用 |
|---|---|---|
observe(target, options) | 开始监听target节点，options声明要监听哪些类型的变化 | observer.observe(ref.current, options) |
disconnect() | 停止监听，之后不再触发回调；已被记录但未交付的变化也会被丢弃 | 卸载清理函数中调用 |
takeRecords() | 取出当前已记录但尚未交付给回调的MutationRecord列表并清空队列 | 本 Hook 未使用，属于进阶能力 |
observe()的第二个参数options即MutationObserverInit，Hook 的默认值全部为true，含义如下：
| 配置项 | 默认值（本 Hook） | 含义 |
|---|---|---|
attributes | true | 监听目标节点属性的变化（如style、class、id） |
characterData | true | 监听目标节点文本内容的变化（适用于文本节点） |
childList | true | 监听目标节点子节点的添加与移除 |
subtree | true | 将监听范围扩展到目标节点的所有后代节点 |
此外MutationObserverInit还支持三个可选配置：attributeOldValue（记录属性变化前的旧值，需与attributes: true搭配）、characterDataOldValue（记录文本变化前的旧值）、attributeFilter（属性名白名单数组，只监听列出的属性）。从源码结构看，本 Hook 只暴露了前四个常用开关，没有透传后三个——如果你的业务需要旧值或属性白名单，可以自行在调用处传入这些字段，observe()会原样接受。
MutationObserver的回调签名是(mutationsList, observer) => void，其中mutationsList是本次批量交付的MutationRecord数组，每个MutationRecord包含type（attributes/characterData/childList）、target、addedNodes、removedNodes、attributeName等字段。本 Hook 直接把这个回调透传给new MutationObserver(callback)，所以你可以自由选择"只计数"或"逐条处理 record"两种用法。
四、完整可运行示例：编辑文本并实时统计变更次数
原文档还附带了一个完整的 Demo（见 snippets/use-mutation-observer.md#L39-L82），它用useMutationObserver统计目标区域被修改的次数：
const App = () => { const mutationRef = React.useRef(); const [mutationCount, setMutationCount] = React.useState(0); const incrementMutationCount = () => { return setMutationCount(mutationCount + 1); }; useMutationObserver(mutationRef, incrementMutationCount); const [content, setContent] = React.useState('Hello world'); return ( <> <label for="content-input">Edit this to update the text:</label> <textarea id="content-input" style={{ width: '100%' }} value={content} onChange={e => setContent(e.target.value)} /> <div style={{ width: '100%' }} ref={mutationRef} > <div style={{ resize: 'both', overflow: 'auto', maxWidth: '100%', border: '1px solid black', }} > <h2>Resize or change the content:</h2> <p>{content}</p> </div> </div> <div> <h3>Mutation count {mutationCount}</h3> </div> </> ); }; ReactDOM.createRoot(document.getElementById('root')).render( <App /> );这个 Demo 演示了两个触发观察器的途径：
- 文本变化：在
textarea中编辑会更新contentstate，进而改变<p>{content}</p>的文本。由于默认配置里characterData: true且subtree: true，文本节点的变化会被捕获，incrementMutationCount被调用，mutationCount增加； - 属性变化：内层
div设置了resize: 'both'，用户拖动右下角改变元素尺寸时，浏览器会改写其style属性，同样触发attributes类型的 mutation。
从渲染方式看，Demo 使用ReactDOM.createRoot(...).render(...)，对应 React 18+ 的并发根渲染 API，说明该片段面向现代 React 版本。运行前只需确保目标容器<div id="root">存在，并把React、ReactDOM作为全局对象引入即可（示例本身不包含 import 语句）。
五、生命周期设计：为什么必须disconnect()
MutationObserver一旦observe()就会持续投递变化通知，如果组件卸载后观察器仍然存活，会导致两个问题：
- 内存泄漏：观察器与目标节点互相引用，目标节点即使被移除出文档，观察器仍可能使其无法被回收；
- 无效回调：卸载后的组件 state 更新会触发 React 的"在已卸载组件上更新状态"警告，甚至引发不必要的重渲染。
因此 Hook 在useEffect()里返回() => observer.disconnect()作为清理函数。这个清理函数不仅在组件卸载时执行，也会在依赖项[callback, options]变化导致 Effect 重跑之前执行——也就是说"旧观察器先断开、新观察器再建立"，整个过程不会出现两个观察器同时监听同一节点的窗口期。
对比仓库中另一个基于 Observer API 的片段 snippets/use-intersection-observer.md：它的清理函数调用的是observer.unobserve(ref.current)而非disconnect()。两者语义不同——unobserve(target)只移除对单个目标的监听，disconnect()则清除该观察器的全部监听。由于useMutationObserver每个 Effect 实例只新建一个观察器、只监听一个节点，用disconnect()是更彻底的收尾方式，两者在这个场景下效果等价。
六、边界情况与实战避坑指南
结合源码结构与MutationObserver的平台行为，使用这个 Hook 时有几点值得注意：
1.ref.current可能尚未就绪。如果ref指向的元素在 Effect 执行时还没有挂载，if (ref.current)分支不成立，观察器不会被创建。这与仓库中useIntersectionObserver的处理方式一致（先if (ref.current)再observe）。若目标元素是异步渲染的，需要确保传给 Hook 的ref在依赖项变化时能让 Effect 重跑，或改用回调 ref 模式。
2.options对象的引用稳定性决定观察器是否频繁重建。从源码结构看，依赖数组[callback, options]使用引用相等比较。如果调用方每次渲染都内联创建新的options对象字面量（如useMutationObserver(ref, cb, { attributes: true })），那么每次渲染都会触发 Effect 重跑、反复断开并重建观察器。建议将options用useMemo()缓存，将callback用useCallback()缓存，这也是该仓库其他片段（如 snippets/use-hover.md 用useCallback缓存事件处理器）的常见做法。
3. 回调内的 stale closure 问题。Demo 中的incrementMutationCount直接使用setMutationCount(mutationCount + 1)。由于MutationObserver回调是微任务批量投递的，一次渲染周期内可能连续触发多次 mutation；如果回调闭包捕获的是旧的mutationCount，计数可能不准。更稳健的写法是函数式更新：setMutationCount(count => count + 1)。这是对原示例的合理改进建议，不影响其演示价值。
4. 全量监听有性能成本。默认配置把attributes、characterData、childList、subtree全部打开，等于监听目标节点整棵子树的一切变化。对高频更新的巨型子树，回调可能被频繁触发。实战中应尽量收窄监听范围：能用childList就不开subtree，能靠attributeFilter白名单就不监听全部属性。
5. 服务端渲染（SSR）注意。MutationObserver是浏览器 API，useEffect()本身只在客户端执行，所以该 Hook 在 SSR 下不会抛错；但ref.current在服务端为null，观察器不会创建，属于预期行为。
七、典型应用场景
基于以上能力，useMutationObserver适合以下实际需求：
- 内容编辑统计：监听
contentEditable区域或富文本区域的文本变化，用于自动保存、字数统计或"未保存修改"提示； - DOM 被外部脚本修改的感知：监听某个容器，当第三方脚本注入节点、改写样式或插入广告时及时响应；
- 自定义组件状态同步：监听子组件内部对某个节点属性的修改，把变化同步回 React state；
- 无障碍与布局响应：结合
attributes监听，感知元素尺寸/类名被程序化改变后触发联动逻辑。
八、仓库定位与本片段的延伸阅读
useMutationObserver属于 30-seconds-of-react 仓库的 hooks 类片段集合。该仓库以"短小、可复用、面向真实问题"为准则（见 CONTRIBUTING.md），每个片段遵循 snippet-template.md 的格式：frontmatter 元数据 + 简述 + 分步原理 + 可运行示例。如果你对"在 React 中封装浏览器 Observer API"这一主题感兴趣，仓库中还有两个高度相关的姊妹片段值得对照阅读：
- snippets/use-intersection-observer.md：用
IntersectionObserver判断元素是否进入视口，返回布尔 state； - snippets/use-hover.md：用事件监听 + 回调 ref 实现悬停状态检测，展示了 ref 传递的另一种模式。
它们共同构成了理解"React Hook 如何托管浏览器异步 API 生命周期"的完整样例集：创建 → 绑定 → 清理三步，是这些片段一致的核心骨架。
小结
useMutationObserver用约 30 行代码，把MutationObserver的创建、监听配置、依赖更新与卸载清理完整封装进 React 生命周期，开箱即用且零依赖。理解它的关键在于三件事：MutationObserverInit各开关对应哪类 DOM 变化、[callback, options]依赖数组如何驱动观察器重建、disconnect()清理如何避免泄漏。在这个基础上，再根据实际场景收窄监听范围、缓存回调与配置，就能在生产环境中稳定使用。
- 前端
- 教程
【免费下载链接】30-seconds-of-react
Short React code snippets for all your development needs
相关推荐
30-seconds-of-code：用 React useMutationObserver Hook 以声明式方式监听 DOM 变化
30 seconds of code：用 React useMutationObserver Hook 以声明式方式监听 DOM 变化 本文基于 30 seco
教程文档30 seconds of React：手写 useIntersectionObserver Hook，监听元素可见性
30 seconds of React：手写 useIntersectionObserver Hook，监听元素可见性 本指南以 30 seconds of r
前端教程30-seconds-of-code React useTimeout Hook：用自定义 Hook 声明式封装 setTimeout 定时器
30 seconds of code React useTimeout Hook：用自定义 Hook 声明式封装 setTimeout 定时器 setTimeo
教程文档
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
